SealDrop Book a demo

API reference

Base address: https://api.sealdrop.ca. Authentication: Authorization: Bearer sd_live_… (see the guide). Machine-readable: openapi.json and the Postman collection.

GET /v1/me

The organization and key making the call. Check that a key works, and read its organization, scopes and limits. Any valid key can call it.

Scope: any valid key.

curl https://api.sealdrop.ca/v1/me \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
organizationobject
organization.idstringThe organization's id.
organization.namestringIts name, as its clients see it.
organization.timeZonestringIANA time zone, e.g. America/Toronto. All API times are UTC; use this to show them.
keyobject
key.idstringThe key's id (it appears in the organization's audit log).
key.namestringThe name the admin gave the key.
key.mode"live" | "test"test keys never email or text a real person.
key.scopesarray of "requests:read" | "files:read" | "answers:read" | "requests:write" | "audit:read" | "contacts:read" | "contacts:write" | "sends:write" | "forms:read" | "forms:write"What this key may do.
key.expiresAtstringWhen the key stops working. ISO 8601, UTC.
limitsobject
limits.perMinuteintegerCalls per minute for this key.
limits.perDayintegerCalls per day for the whole organization.

Example answer (made-up data):

{
  "organization": {
    "id": "3f8a2c1e-5b7d-4e9f-a1c3-0d2b4f6e8a10",
    "name": "Ledger & Co.",
    "timeZone": "America/Toronto"
  },
  "key": {
    "id": "9c1d7e3a-2f4b-4a6c-8e0d-1b3f5a7c9e21",
    "name": "Tax software integration",
    "mode": "test",
    "scopes": [
      "requests:read",
      "files:read",
      "answers:read",
      "audit:read"
    ],
    "expiresAt": "2027-10-22T17:00:00.000Z"
  },
  "limits": {
    "perMinute": 60,
    "perDay": 5000
  }
}

GET /v1/requests

List requests. Newest first, 50 a page (up to 200). Filter by status, by when they were submitted or created. To follow changes as they happen, use the events feed (GET /v1/events) instead of listing again and again.

Scope: requests:read.

curl https://api.sealdrop.ca/v1/requests \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
requestsarray of object
nextCursorstring,nullPass as cursor for the next page; null on the last.

Example answer (made-up data):

{
  "requests": [
    {
      "id": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
      "reference": "SD-5D0B8C2A-7E1F",
      "status": "received",
      "test": false,
      "person": {
        "name": "Amara Okafor",
        "email": "amara.okafor@example.com",
        "mobile": "+16045550100"
      },
      "source": "app",
      "openLinkId": null,
      "channels": [
        "email"
      ],
      "note": "Please upload your 2025 tax slips.",
      "message": "My second T4 is still coming.",
      "questionnaire": {
        "name": "Personal tax return checklist"
      },
      "filesRequired": true,
      "fileCount": 2,
      "blockedFiles": 0,
      "createdAt": "2026-10-21T16:20:00.000Z",
      "submittedAt": "2026-10-23T17:42:10.000Z",
      "linkExpiresAt": "2026-10-28T16:20:00.000Z",
      "deleteAt": "2026-11-22T17:42:10.000Z",
      "filesDeletedAt": null,
      "importedAt": null
    }
  ],
  "nextCursor": "eyJpZCI6Ij…"
}

GET /v1/requests/{id}

One request, with its files. Everything the staff app's request page shows: who it went to, the note, the person's reply, the questionnaire, its files and their malware-scan status, and when it will be deleted. Reading it doesn't mark it as seen for staff.

Scope: requests:read.

curl https://api.sealdrop.ca/v1/requests/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
referencestringThe SealDrop reference (SD-…) people see. Never put it in a URL.
status"sent" | "received" | "downloaded" | "filed" | "expired" | "cancelled"sent → received (the person submitted) → downloaded → filed. Or expired / cancelled.
testbooleanMade with a test key. Test keys see only test requests; live keys never see them.
personobjectWho it was sent to, as entered (for an open link, as the person typed it).
person.namestring
person.emailstring,null
person.mobilestring,nullE.164, e.g. +16045550123.
source"app" | "api" | "open_link" | "group_send" | "recurring"Where it came from: sent in the app, through the API, started by the person on an open link, part of a group send, or a recurring request.
openLinkIdstring,nullFor open_link: which open link.
channelsarray of "email" | "sms"
notestring,nullThe note shown to the person.
messagestring,nullThe person's reply message, when replies were allowed.
questionnaireobject
filesRequiredboolean
fileCountintegerFiles the person uploaded (not counting the answers PDF).
blockedFilesintegerFiles deleted by the malware scan.
createdAtstringISO 8601, UTC.
submittedAtstring,nullISO 8601, UTC, or null.
linkExpiresAtstringISO 8601, UTC.
deleteAtstring,nullWhen SealDrop deletes the files, if nobody does sooner.
filesDeletedAtstring,nullISO 8601, UTC, or null.
importedAtstring,nullWhen a system confirmed it imported the documents (POST …/imported).
filesarray of object

Example answer (made-up data):

{
  "id": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
  "reference": "SD-5D0B8C2A-7E1F",
  "status": "received",
  "test": false,
  "person": {
    "name": "Amara Okafor",
    "email": "amara.okafor@example.com",
    "mobile": "+16045550100"
  },
  "source": "app",
  "openLinkId": null,
  "channels": [
    "email"
  ],
  "note": "Please upload your 2025 tax slips.",
  "message": "My second T4 is still coming.",
  "questionnaire": {
    "name": "Personal tax return checklist"
  },
  "filesRequired": true,
  "fileCount": 2,
  "blockedFiles": 0,
  "createdAt": "2026-10-21T16:20:00.000Z",
  "submittedAt": "2026-10-23T17:42:10.000Z",
  "linkExpiresAt": "2026-10-28T16:20:00.000Z",
  "deleteAt": "2026-11-22T17:42:10.000Z",
  "filesDeletedAt": null,
  "importedAt": null,
  "files": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Amara Okafor - T4 2025 (SD-5D0B8C2A-7E1F).pdf",
      "contentType": "application/pdf",
      "size": 184220,
      "kind": "upload",
      "scan": "clean",
      "deleted": false,
      "uploadedAt": "2026-10-23T17:41:02.000Z",
      "downloadedAt": null
    },
    {
      "id": "7b2e9f10-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
      "name": "Amara Okafor - Personal tax return checklist (SD-5D0B8C2A-7E1F).pdf",
      "contentType": "application/pdf",
      "size": 52310,
      "kind": "answers",
      "scan": "clean",
      "deleted": false,
      "uploadedAt": "2026-10-23T17:42:10.000Z",
      "downloadedAt": null
    }
  ]
}

GET /v1/files/{id}/download

A download link for one file. A link to the malware-scanned copy, valid 5 minutes — GET it without an Authorization header. 409 still_scanning means try again shortly; 409 blocked, the scan deleted it; 410, it is already deleted. The first download of a request starts its deletion clock, exactly as when staff download.

Scope: files:read.

curl https://api.sealdrop.ca/v1/files/{id}/download \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
urlstringA link to the clean copy. GET it within 5 minutes; no Authorization header.
expiresAtstringISO 8601, UTC.

Example answer (made-up data):

{
  "url": "https://…s3.ca-central-1.amazonaws.com/…?X-Amz-Expires=300&…",
  "expiresAt": "2026-10-23T18:05:00.000Z"
}

GET /v1/requests/{id}/answers

The questionnaire answers, as data. Each question with its stable name, its title and the answer — to fill your own fields. The same answers are in the answers PDF among the files. 404 when the request had no questionnaire; 410 once its files were deleted.

Scope: answers:read.

curl https://api.sealdrop.ca/v1/requests/{id}/answers \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
questionnaireobject
questionnaire.namestring
submittedAtstringISO 8601, UTC.
answersarray of object
pdfFileIdstring,nullThe answers PDF among the request’s files.
scoresarray of objectThe questionnaire’s own scores, worked out by SealDrop on submit (empty when it has none).
calculationsarray of objectThe questionnaire’s calculations that have a value (ages, totals, formulas).
flagsarray of stringWhy the request needs review: the organization’s own reasons, from its flag rules.

Example answer (made-up data):

{
  "questionnaire": {
    "name": "Personal tax return checklist"
  },
  "submittedAt": "2026-10-23T17:42:10.000Z",
  "answers": [
    {
      "name": "dateOfBirth",
      "title": "Date of birth",
      "type": "text",
      "value": "1984-03-09"
    },
    {
      "name": "q1",
      "title": "Which tax year is this for?",
      "type": "dropdown",
      "value": "2025"
    },
    {
      "name": "q2",
      "title": "Income you had this year",
      "type": "checkbox",
      "value": [
        "Employment (T4)",
        "RRSP or RRIF withdrawals"
      ]
    },
    {
      "name": "q3",
      "title": "Did your marital status or address change?",
      "type": "boolean",
      "value": false
    }
  ],
  "pdfFileId": "7b2e9f10-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "scores": [],
  "calculations": [
    {
      "name": "Age",
      "value": 42
    }
  ],
  "flags": []
}

POST /v1/requests/{id}/imported

Confirm your system has the documents. Call it once your system has stored every file (and the answers): SealDrop then deletes its copy right away, as when staff mark a request Filed — so the person's documents live in one place, your system. If the organization chose to have staff look first, the request is marked imported and deleted on its usual schedule. 409 not_downloaded until every clean file has been downloaded at least once; 409 still_scanning while a file is being scanned. Calling it again is safe.

Scope: files:read.

curl https://api.sealdrop.ca/v1/requests/{id}/imported \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
action"deleted" | "kept"deleted: SealDrop is deleting its copy now (the organization’s default). kept: staff review it first, then it is deleted on the usual schedule.
requestobject
request.idstring
request.referencestringThe SealDrop reference (SD-…) people see. Never put it in a URL.
request.status"sent" | "received" | "downloaded" | "filed" | "expired" | "cancelled"sent → received (the person submitted) → downloaded → filed. Or expired / cancelled.
request.testbooleanMade with a test key. Test keys see only test requests; live keys never see them.
request.personobjectWho it was sent to, as entered (for an open link, as the person typed it).
request.person.namestring
request.person.emailstring,null
request.person.mobilestring,nullE.164, e.g. +16045550123.
request.source"app" | "api" | "open_link" | "group_send" | "recurring"Where it came from: sent in the app, through the API, started by the person on an open link, part of a group send, or a recurring request.
request.openLinkIdstring,nullFor open_link: which open link.
request.channelsarray of "email" | "sms"
request.notestring,nullThe note shown to the person.
request.messagestring,nullThe person's reply message, when replies were allowed.
request.questionnaireobject
request.filesRequiredboolean
request.fileCountintegerFiles the person uploaded (not counting the answers PDF).
request.blockedFilesintegerFiles deleted by the malware scan.
request.createdAtstringISO 8601, UTC.
request.submittedAtstring,nullISO 8601, UTC, or null.
request.linkExpiresAtstringISO 8601, UTC.
request.deleteAtstring,nullWhen SealDrop deletes the files, if nobody does sooner.
request.filesDeletedAtstring,nullISO 8601, UTC, or null.
request.importedAtstring,nullWhen a system confirmed it imported the documents (POST …/imported).

Example answer (made-up data):

{
  "action": "deleted",
  "request": {
    "id": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
    "reference": "SD-5D0B8C2A-7E1F",
    "status": "filed",
    "test": false,
    "person": {
      "name": "Amara Okafor",
      "email": "amara.okafor@example.com",
      "mobile": "+16045550100"
    },
    "source": "app",
    "openLinkId": null,
    "channels": [
      "email"
    ],
    "note": "Please upload your 2025 tax slips.",
    "message": "My second T4 is still coming.",
    "questionnaire": {
      "name": "Personal tax return checklist"
    },
    "filesRequired": true,
    "fileCount": 2,
    "blockedFiles": 0,
    "createdAt": "2026-10-21T16:20:00.000Z",
    "submittedAt": "2026-10-23T17:42:10.000Z",
    "linkExpiresAt": "2026-10-28T16:20:00.000Z",
    "deleteAt": "2026-10-23T18:01:12.000Z",
    "filesDeletedAt": null,
    "importedAt": "2026-10-23T18:01:12.000Z"
  }
}

GET /v1/audit

The organization's audit log. Who did what and when — staff, API keys, the people who uploaded, SealDrop itself — with ids, never names of clients, file names or answers. 200 a page, newest first.

Scope: audit:read.

curl https://api.sealdrop.ca/v1/audit \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
eventsarray of object
nextCursorstring,null

Example answer (made-up data):

{
  "events": [
    {
      "at": "2026-10-23T18:00:41.000Z",
      "action": "file.downloaded",
      "actor": "apikey:9c1d7e3a-2f4b-4a6c-8e0d-1b3f5a7c9e21",
      "actorName": "API key “Tax software integration”",
      "ip": "203.0.113.7",
      "requestId": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
      "fileId": "7b2e9f10-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
    }
  ],
  "nextCursor": null
}

GET /v1/events

What happened, in order. A feed of changes — ids and types only, nothing about the person — kept 30 days. Poll it (every minute is plenty), remember nextCursor, and fetch whatever changed. For systems that can't receive webhooks; webhooks will send the same events.

Scope: requests:read.

curl https://api.sealdrop.ca/v1/events \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
eventsarray of object
nextCursorstring,nullPass as after next time; it is returned even on the last page, so you can keep polling from it.

Example answer (made-up data):

{
  "events": [
    {
      "id": "evt_0c7f5e2a-1b3d-4f6a-8c9e-2d4f6a8b0c1e",
      "type": "request.received",
      "at": "2026-10-23T17:42:10.000Z",
      "requestId": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
      "fileId": null
    }
  ],
  "nextCursor": "MjAyNi0xMC0yM1Qx…"
}

POST /v1/requests

Send a request. Sends the secure link by email and/or text, exactly as the app's New request: the organization's wording and branding, its link lifetime, daily limits and plan rules. Needs an Idempotency-Key header (any id of your own, e.g. your record's): a retry with the same key and body within 24 hours returns the first answer instead of sending again. With a test key, the email goes only to the admin who created the key and no text is sent.

Scope: requests:write.

curl https://api.sealdrop.ca/v1/requests \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
requestobject
request.idstring
request.referencestringThe SealDrop reference (SD-…) people see. Never put it in a URL.
request.status"sent" | "received" | "downloaded" | "filed" | "expired" | "cancelled"sent → received (the person submitted) → downloaded → filed. Or expired / cancelled.
request.testbooleanMade with a test key. Test keys see only test requests; live keys never see them.
request.personobjectWho it was sent to, as entered (for an open link, as the person typed it).
request.person.namestring
request.person.emailstring,null
request.person.mobilestring,nullE.164, e.g. +16045550123.
request.source"app" | "api" | "open_link" | "group_send" | "recurring"Where it came from: sent in the app, through the API, started by the person on an open link, part of a group send, or a recurring request.
request.openLinkIdstring,nullFor open_link: which open link.
request.channelsarray of "email" | "sms"
request.notestring,nullThe note shown to the person.
request.messagestring,nullThe person's reply message, when replies were allowed.
request.questionnaireobject
request.filesRequiredboolean
request.fileCountintegerFiles the person uploaded (not counting the answers PDF).
request.blockedFilesintegerFiles deleted by the malware scan.
request.createdAtstringISO 8601, UTC.
request.submittedAtstring,nullISO 8601, UTC, or null.
request.linkExpiresAtstringISO 8601, UTC.
request.deleteAtstring,nullWhen SealDrop deletes the files, if nobody does sooner.
request.filesDeletedAtstring,nullISO 8601, UTC, or null.
request.importedAtstring,nullWhen a system confirmed it imported the documents (POST …/imported).
deliveryobjectPer channel. With a test key: the email goes only to the admin who created the key, and no text is sent.
delivery.email"sent" | "sent_to_test_recipient" | "daily_limit" | "failed"
delivery.sms"sent" | "not_sent_test" | "not_verified" | "opted_out" | "sms_off" | "daily_text_limit" | "number_limit" | "failed"

Example answer (made-up data):

{
  "request": {
    "id": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
    "reference": "SD-5D0B8C2A-7E1F",
    "status": "sent",
    "test": false,
    "person": {
      "name": "Amara Okafor",
      "email": "amara.okafor@example.com",
      "mobile": "+16045550100"
    },
    "source": "app",
    "openLinkId": null,
    "channels": [
      "email"
    ],
    "note": "Please upload your 2025 tax slips.",
    "message": null,
    "questionnaire": {
      "name": "Personal tax return checklist"
    },
    "filesRequired": true,
    "fileCount": 0,
    "blockedFiles": 0,
    "createdAt": "2026-10-21T16:20:00.000Z",
    "submittedAt": null,
    "linkExpiresAt": "2026-10-28T16:20:00.000Z",
    "deleteAt": null,
    "filesDeletedAt": null,
    "importedAt": null
  },
  "delivery": {
    "email": "sent"
  }
}

POST /v1/requests/{id}/resend

Send the link again. A new link replaces the old one (which stops working), sent the same way. Allowed while the request is sent or expired.

Scope: requests:write.

curl https://api.sealdrop.ca/v1/requests/{id}/resend \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
requestobject
request.idstring
request.referencestringThe SealDrop reference (SD-…) people see. Never put it in a URL.
request.status"sent" | "received" | "downloaded" | "filed" | "expired" | "cancelled"sent → received (the person submitted) → downloaded → filed. Or expired / cancelled.
request.testbooleanMade with a test key. Test keys see only test requests; live keys never see them.
request.personobjectWho it was sent to, as entered (for an open link, as the person typed it).
request.person.namestring
request.person.emailstring,null
request.person.mobilestring,nullE.164, e.g. +16045550123.
request.source"app" | "api" | "open_link" | "group_send" | "recurring"Where it came from: sent in the app, through the API, started by the person on an open link, part of a group send, or a recurring request.
request.openLinkIdstring,nullFor open_link: which open link.
request.channelsarray of "email" | "sms"
request.notestring,nullThe note shown to the person.
request.messagestring,nullThe person's reply message, when replies were allowed.
request.questionnaireobject
request.filesRequiredboolean
request.fileCountintegerFiles the person uploaded (not counting the answers PDF).
request.blockedFilesintegerFiles deleted by the malware scan.
request.createdAtstringISO 8601, UTC.
request.submittedAtstring,nullISO 8601, UTC, or null.
request.linkExpiresAtstringISO 8601, UTC.
request.deleteAtstring,nullWhen SealDrop deletes the files, if nobody does sooner.
request.filesDeletedAtstring,nullISO 8601, UTC, or null.
request.importedAtstring,nullWhen a system confirmed it imported the documents (POST …/imported).
deliveryobjectPer channel. With a test key: the email goes only to the admin who created the key, and no text is sent.
delivery.email"sent" | "sent_to_test_recipient" | "daily_limit" | "failed"
delivery.sms"sent" | "not_sent_test" | "not_verified" | "opted_out" | "sms_off" | "daily_text_limit" | "number_limit" | "failed"

Example answer (made-up data):

{
  "request": {
    "id": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
    "reference": "SD-5D0B8C2A-7E1F",
    "status": "sent",
    "test": false,
    "person": {
      "name": "Amara Okafor",
      "email": "amara.okafor@example.com",
      "mobile": "+16045550100"
    },
    "source": "app",
    "openLinkId": null,
    "channels": [
      "email"
    ],
    "note": "Please upload your 2025 tax slips.",
    "message": null,
    "questionnaire": {
      "name": "Personal tax return checklist"
    },
    "filesRequired": true,
    "fileCount": 0,
    "blockedFiles": 0,
    "createdAt": "2026-10-21T16:20:00.000Z",
    "submittedAt": null,
    "linkExpiresAt": "2026-10-28T16:20:00.000Z",
    "deleteAt": null,
    "filesDeletedAt": null,
    "importedAt": null
  },
  "delivery": {
    "email": "sent"
  }
}

POST /v1/requests/{id}/cancel

Cancel a request. The link stops working and anything uploaded is deleted right away.

Scope: requests:write.

curl https://api.sealdrop.ca/v1/requests/{id}/cancel \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
requestobject
request.idstring
request.referencestringThe SealDrop reference (SD-…) people see. Never put it in a URL.
request.status"sent" | "received" | "downloaded" | "filed" | "expired" | "cancelled"sent → received (the person submitted) → downloaded → filed. Or expired / cancelled.
request.testbooleanMade with a test key. Test keys see only test requests; live keys never see them.
request.personobjectWho it was sent to, as entered (for an open link, as the person typed it).
request.person.namestring
request.person.emailstring,null
request.person.mobilestring,nullE.164, e.g. +16045550123.
request.source"app" | "api" | "open_link" | "group_send" | "recurring"Where it came from: sent in the app, through the API, started by the person on an open link, part of a group send, or a recurring request.
request.openLinkIdstring,nullFor open_link: which open link.
request.channelsarray of "email" | "sms"
request.notestring,nullThe note shown to the person.
request.messagestring,nullThe person's reply message, when replies were allowed.
request.questionnaireobject
request.filesRequiredboolean
request.fileCountintegerFiles the person uploaded (not counting the answers PDF).
request.blockedFilesintegerFiles deleted by the malware scan.
request.createdAtstringISO 8601, UTC.
request.submittedAtstring,nullISO 8601, UTC, or null.
request.linkExpiresAtstringISO 8601, UTC.
request.deleteAtstring,nullWhen SealDrop deletes the files, if nobody does sooner.
request.filesDeletedAtstring,nullISO 8601, UTC, or null.
request.importedAtstring,nullWhen a system confirmed it imported the documents (POST …/imported).

Example answer (made-up data):

{
  "request": {
    "id": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
    "reference": "SD-5D0B8C2A-7E1F",
    "status": "cancelled",
    "test": false,
    "person": {
      "name": "Amara Okafor",
      "email": "amara.okafor@example.com",
      "mobile": "+16045550100"
    },
    "source": "app",
    "openLinkId": null,
    "channels": [
      "email"
    ],
    "note": "Please upload your 2025 tax slips.",
    "message": "My second T4 is still coming.",
    "questionnaire": {
      "name": "Personal tax return checklist"
    },
    "filesRequired": true,
    "fileCount": 2,
    "blockedFiles": 0,
    "createdAt": "2026-10-21T16:20:00.000Z",
    "submittedAt": "2026-10-23T17:42:10.000Z",
    "linkExpiresAt": "2026-10-28T16:20:00.000Z",
    "deleteAt": "2026-11-22T17:42:10.000Z",
    "filesDeletedAt": null,
    "importedAt": null
  }
}

POST /v1/requests/{id}/filed

Mark a request filed. As Filed in the app: its files are deleted right away. After downloading, prefer POST /v1/requests/{id}/imported, which also checks every file was fetched.

Scope: requests:write.

curl https://api.sealdrop.ca/v1/requests/{id}/filed \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
requestobject
request.idstring
request.referencestringThe SealDrop reference (SD-…) people see. Never put it in a URL.
request.status"sent" | "received" | "downloaded" | "filed" | "expired" | "cancelled"sent → received (the person submitted) → downloaded → filed. Or expired / cancelled.
request.testbooleanMade with a test key. Test keys see only test requests; live keys never see them.
request.personobjectWho it was sent to, as entered (for an open link, as the person typed it).
request.person.namestring
request.person.emailstring,null
request.person.mobilestring,nullE.164, e.g. +16045550123.
request.source"app" | "api" | "open_link" | "group_send" | "recurring"Where it came from: sent in the app, through the API, started by the person on an open link, part of a group send, or a recurring request.
request.openLinkIdstring,nullFor open_link: which open link.
request.channelsarray of "email" | "sms"
request.notestring,nullThe note shown to the person.
request.messagestring,nullThe person's reply message, when replies were allowed.
request.questionnaireobject
request.filesRequiredboolean
request.fileCountintegerFiles the person uploaded (not counting the answers PDF).
request.blockedFilesintegerFiles deleted by the malware scan.
request.createdAtstringISO 8601, UTC.
request.submittedAtstring,nullISO 8601, UTC, or null.
request.linkExpiresAtstringISO 8601, UTC.
request.deleteAtstring,nullWhen SealDrop deletes the files, if nobody does sooner.
request.filesDeletedAtstring,nullISO 8601, UTC, or null.
request.importedAtstring,nullWhen a system confirmed it imported the documents (POST …/imported).

Example answer (made-up data):

{
  "request": {
    "id": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
    "reference": "SD-5D0B8C2A-7E1F",
    "status": "filed",
    "test": false,
    "person": {
      "name": "Amara Okafor",
      "email": "amara.okafor@example.com",
      "mobile": "+16045550100"
    },
    "source": "app",
    "openLinkId": null,
    "channels": [
      "email"
    ],
    "note": "Please upload your 2025 tax slips.",
    "message": "My second T4 is still coming.",
    "questionnaire": {
      "name": "Personal tax return checklist"
    },
    "filesRequired": true,
    "fileCount": 2,
    "blockedFiles": 0,
    "createdAt": "2026-10-21T16:20:00.000Z",
    "submittedAt": "2026-10-23T17:42:10.000Z",
    "linkExpiresAt": "2026-10-28T16:20:00.000Z",
    "deleteAt": "2026-11-22T17:42:10.000Z",
    "filesDeletedAt": null,
    "importedAt": null
  }
}

GET /v1/questionnaires

The organization's questionnaires. Ids and names, to choose one when sending a request.

Scope: forms:read.

curl https://api.sealdrop.ca/v1/questionnaires \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
questionnairesarray of object

Example answer (made-up data):

{
  "questionnaires": [
    {
      "id": "2c4e6a8b-0d1f-4a3b-8c5d-7e9f1a2b3c4d",
      "name": "Personal tax return checklist",
      "questionCount": 12
    }
  ]
}

GET /v1/email-designs

The organization's email designs. Ids and names of the designed emails; one may be the default.

Scope: forms:read.

curl https://api.sealdrop.ca/v1/email-designs \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
designsarray of object

Example answer (made-up data):

{
  "designs": [
    {
      "id": "8e1f3a5c-7b9d-4e2f-a6c8-0b2d4f6a8c1e",
      "name": "Tax season",
      "isDefault": true
    }
  ]
}

POST /v1/test/requests/{id}/simulate-upload

Play the person's part (test keys only). For a request made with a test key: SealDrop uploads its own sample PDF and photo, fills the questionnaire with sample answers, and submits — through the real malware scan, so the files become downloadable a minute or two later, exactly as a real upload would. Live keys get 403.

Scope: requests:write.

curl https://api.sealdrop.ca/v1/test/requests/{id}/simulate-upload \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
requestobject
request.idstring
request.referencestringThe SealDrop reference (SD-…) people see. Never put it in a URL.
request.status"sent" | "received" | "downloaded" | "filed" | "expired" | "cancelled"sent → received (the person submitted) → downloaded → filed. Or expired / cancelled.
request.testbooleanMade with a test key. Test keys see only test requests; live keys never see them.
request.personobjectWho it was sent to, as entered (for an open link, as the person typed it).
request.person.namestring
request.person.emailstring,null
request.person.mobilestring,nullE.164, e.g. +16045550123.
request.source"app" | "api" | "open_link" | "group_send" | "recurring"Where it came from: sent in the app, through the API, started by the person on an open link, part of a group send, or a recurring request.
request.openLinkIdstring,nullFor open_link: which open link.
request.channelsarray of "email" | "sms"
request.notestring,nullThe note shown to the person.
request.messagestring,nullThe person's reply message, when replies were allowed.
request.questionnaireobject
request.filesRequiredboolean
request.fileCountintegerFiles the person uploaded (not counting the answers PDF).
request.blockedFilesintegerFiles deleted by the malware scan.
request.createdAtstringISO 8601, UTC.
request.submittedAtstring,nullISO 8601, UTC, or null.
request.linkExpiresAtstringISO 8601, UTC.
request.deleteAtstring,nullWhen SealDrop deletes the files, if nobody does sooner.
request.filesDeletedAtstring,nullISO 8601, UTC, or null.
request.importedAtstring,nullWhen a system confirmed it imported the documents (POST …/imported).

Example answer (made-up data):

{
  "request": {
    "id": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d",
    "reference": "SD-5D0B8C2A-7E1F",
    "status": "received",
    "test": true,
    "person": {
      "name": "Test Person",
      "email": "test@example.com",
      "mobile": null
    },
    "source": "app",
    "openLinkId": null,
    "channels": [
      "email"
    ],
    "note": "Please upload your 2025 tax slips.",
    "message": "My second T4 is still coming.",
    "questionnaire": {
      "name": "Personal tax return checklist"
    },
    "filesRequired": true,
    "fileCount": 2,
    "blockedFiles": 0,
    "createdAt": "2026-10-21T16:20:00.000Z",
    "submittedAt": "2026-10-23T17:42:10.000Z",
    "linkExpiresAt": "2026-10-28T16:20:00.000Z",
    "deleteAt": "2026-11-22T17:42:10.000Z",
    "filesDeletedAt": null,
    "importedAt": null
  }
}

GET /v1/contacts

List contacts. 2,500 a page. With updatedSince (from the last page’s asOf), only what changed — and the ids deleted since — so your system can stay in step cheaply.

Scope: contacts:read.

curl https://api.sealdrop.ca/v1/contacts \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
contactsarray of object
deletedarray of stringWith updatedSince: ids deleted since then.
nextCursorstring,null
asOfstringPass as updatedSince next time to get only what changed.

GET /v1/contacts/{id}

One contact. Name, email, mobile, groups, whether they may be contacted, and when they’d be deleted for inactivity.

Scope: contacts:read.

curl https://api.sealdrop.ca/v1/contacts/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
emailstring,null
mobilestring,nullE.164, e.g. +16045550123.
dateOfBirthstring,nullYYYY-MM-DD, when known: entered by staff, given on a sign-up page or an open link’s questionnaire, or set through the API.
idNumberstring,nullThe organization’s client ID (a government-issued number or its own, as set in Settings), whole; null when the client has none. Staff see it masked in the app.
source"app" | "api" | "import" | "signup_page" | "open_link"How they were added.
sourceIdstring,nullFor signup_page and open_link: which page or link.
signupobjectWhat they answered on a sign-up page — their latest sign-up.
groupIdsarray of string
doNotContactbooleanThey unsubscribed or staff marked them: no bulk requests.
emailStatus"ok" | "bounced" | "complained"
lastActivityAtstringISO 8601, UTC.
deleteOnstringYYYY-MM-DD: deleted automatically after 24 months without activity.
createdAtstringISO 8601, UTC.
updatedAtstringISO 8601, UTC.

POST /v1/contacts

Add a contact. One contact per email, per mobile and per client ID in the organization: one already used → 409 duplicate_email (or duplicate_phone, duplicate_idNumber) with the existing contactId. Needs consent.confirmed.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/contacts \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
emailstring,null
mobilestring,nullE.164, e.g. +16045550123.
dateOfBirthstring,nullYYYY-MM-DD, when known: entered by staff, given on a sign-up page or an open link’s questionnaire, or set through the API.
idNumberstring,nullThe organization’s client ID (a government-issued number or its own, as set in Settings), whole; null when the client has none. Staff see it masked in the app.
source"app" | "api" | "import" | "signup_page" | "open_link"How they were added.
sourceIdstring,nullFor signup_page and open_link: which page or link.
signupobjectWhat they answered on a sign-up page — their latest sign-up.
groupIdsarray of string
doNotContactbooleanThey unsubscribed or staff marked them: no bulk requests.
emailStatus"ok" | "bounced" | "complained"
lastActivityAtstringISO 8601, UTC.
deleteOnstringYYYY-MM-DD: deleted automatically after 24 months without activity.
createdAtstringISO 8601, UTC.
updatedAtstringISO 8601, UTC.

POST /v1/contacts/bulk

Add or update up to 500 contacts. For each row: a new person is created, one whose email or mobile is already in Contacts is updated (name, and added to the groups), anything invalid is skipped with the reason. One result per row, in order.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/contacts/bulk \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
resultsarray of object
createdinteger
updatedinteger
skippedinteger

PUT /v1/contacts/{id}

Change a contact. Name, email or mobile.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/contacts/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
emailstring,null
mobilestring,nullE.164, e.g. +16045550123.
dateOfBirthstring,nullYYYY-MM-DD, when known: entered by staff, given on a sign-up page or an open link’s questionnaire, or set through the API.
idNumberstring,nullThe organization’s client ID (a government-issued number or its own, as set in Settings), whole; null when the client has none. Staff see it masked in the app.
source"app" | "api" | "import" | "signup_page" | "open_link"How they were added.
sourceIdstring,nullFor signup_page and open_link: which page or link.
signupobjectWhat they answered on a sign-up page — their latest sign-up.
groupIdsarray of string
doNotContactbooleanThey unsubscribed or staff marked them: no bulk requests.
emailStatus"ok" | "bounced" | "complained"
lastActivityAtstringISO 8601, UTC.
deleteOnstringYYYY-MM-DD: deleted automatically after 24 months without activity.
createdAtstringISO 8601, UTC.
updatedAtstringISO 8601, UTC.

DELETE /v1/contacts/{id}

Delete a contact. Gone for good; their requests keep their own deletion schedule.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/contacts/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
okboolean

POST /v1/contacts/{id}/do-not-contact

Mark “don’t contact”. No bulk requests from then on. Lifting it is for an admin, in the app.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/contacts/{id}/do-not-contact \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
emailstring,null
mobilestring,nullE.164, e.g. +16045550123.
dateOfBirthstring,nullYYYY-MM-DD, when known: entered by staff, given on a sign-up page or an open link’s questionnaire, or set through the API.
idNumberstring,nullThe organization’s client ID (a government-issued number or its own, as set in Settings), whole; null when the client has none. Staff see it masked in the app.
source"app" | "api" | "import" | "signup_page" | "open_link"How they were added.
sourceIdstring,nullFor signup_page and open_link: which page or link.
signupobjectWhat they answered on a sign-up page — their latest sign-up.
groupIdsarray of string
doNotContactbooleanThey unsubscribed or staff marked them: no bulk requests.
emailStatus"ok" | "bounced" | "complained"
lastActivityAtstringISO 8601, UTC.
deleteOnstringYYYY-MM-DD: deleted automatically after 24 months without activity.
createdAtstringISO 8601, UTC.
updatedAtstringISO 8601, UTC.

GET /v1/groups

List groups. Ids, names and colours.

Scope: contacts:read.

curl https://api.sealdrop.ca/v1/groups \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
groupsarray of object

POST /v1/groups

Make a group. A name and an optional colour.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/groups \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
colour"teal" | "blue" | "violet" | "pink" | "orange" | "amber" | "green" | "grey"
createdAtstringISO 8601, UTC.

PUT /v1/groups/{id}

Rename a group. A new name or colour.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/groups/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
colour"teal" | "blue" | "violet" | "pink" | "orange" | "amber" | "green" | "grey"
createdAtstringISO 8601, UTC.

DELETE /v1/groups/{id}

Delete a group. Its contacts stay; they just leave the group.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/groups/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
okboolean

POST /v1/groups/{id}/members

Add or remove members. Contact ids to add to and remove from the group, up to 500 each.

Scope: contacts:write.

curl https://api.sealdrop.ca/v1/groups/{id}/members \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
updatedinteger

POST /v1/sends

Send to groups or everyone. The app's Group or everyone: one request each, in waves within sending hours, with the organization's daily and monthly limits, the bounce and complaint safety stops, and unsubscribe. People with no email, marked don't contact, bounced or reported before, or sent one recently are skipped. Needs group sending on the plan and the bulk-sending terms accepted by an admin in the app. sendAt sends later. Test keys can't send to groups.

Scope: sends:write.

curl https://api.sealdrop.ca/v1/sends \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
status"started" | "scheduled"
sendobjectWhen started now.
queuedobject
skippedobjectPeople skipped: no email, don’t contact, bounced or reported before, sent too recently.
scheduledobjectWhen sent later.

GET /v1/sends

Group sends so far. Newest first, with their counts.

Scope: sends:write.

curl https://api.sealdrop.ca/v1/sends \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
sendsarray of object

GET /v1/sends/{id}

One group send. Its status and counts.

Scope: sends:write.

curl https://api.sealdrop.ca/v1/sends/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
status"importing" | "queued" | "sending" | "paused" | "finished" | "cancelled"
createdAtstringISO 8601, UTC.
queuedintegerPeople queued (sent ones included).
skippedinteger
sentinteger
bouncedinteger
complainedinteger
unsubscribedintegerPeople who unsubscribed with this send’s link.
startedAtobject
nextWaveAtobjectSends go out in waves within sending hours, at the organization’s daily limit.
finishEstimatestring,null
pausedReasonobjectPaused by SealDrop’s safety stops; resuming needs acknowledged: true.

GET /v1/sends/{id}/results

Who it went to, and what happened. Per person: their request, whether it was sent, bounced, reported or answered.

Scope: sends:write.

curl https://api.sealdrop.ca/v1/sends/{id}/results \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
sendobject
send.idstring
send.status"importing" | "queued" | "sending" | "paused" | "finished" | "cancelled"
send.createdAtstringISO 8601, UTC.
send.queuedintegerPeople queued (sent ones included).
send.skippedinteger
send.sentinteger
send.bouncedinteger
send.complainedinteger
send.unsubscribedintegerPeople who unsubscribed with this send’s link.
send.startedAtobject
send.nextWaveAtobjectSends go out in waves within sending hours, at the organization’s daily limit.
send.finishEstimatestring,null
send.pausedReasonobjectPaused by SealDrop’s safety stops; resuming needs acknowledged: true.
peoplearray of object

POST /v1/sends/{id}/pause

Pause a group send. No more waves until it is resumed.

Scope: sends:write.

curl https://api.sealdrop.ca/v1/sends/{id}/pause \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
status"importing" | "queued" | "sending" | "paused" | "finished" | "cancelled"
createdAtstringISO 8601, UTC.
queuedintegerPeople queued (sent ones included).
skippedinteger
sentinteger
bouncedinteger
complainedinteger
unsubscribedintegerPeople who unsubscribed with this send’s link.
startedAtobject
nextWaveAtobjectSends go out in waves within sending hours, at the organization’s daily limit.
finishEstimatestring,null
pausedReasonobjectPaused by SealDrop’s safety stops; resuming needs acknowledged: true.

POST /v1/sends/{id}/resume

Resume a group send. After a safety stop (pausedReason), pass acknowledged: true.

Scope: sends:write.

curl https://api.sealdrop.ca/v1/sends/{id}/resume \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
status"importing" | "queued" | "sending" | "paused" | "finished" | "cancelled"
createdAtstringISO 8601, UTC.
queuedintegerPeople queued (sent ones included).
skippedinteger
sentinteger
bouncedinteger
complainedinteger
unsubscribedintegerPeople who unsubscribed with this send’s link.
startedAtobject
nextWaveAtobjectSends go out in waves within sending hours, at the organization’s daily limit.
finishEstimatestring,null
pausedReasonobjectPaused by SealDrop’s safety stops; resuming needs acknowledged: true.

POST /v1/sends/{id}/cancel

Cancel a group send. People not sent yet are dropped; those already sent keep their links.

Scope: sends:write.

curl https://api.sealdrop.ca/v1/sends/{id}/cancel \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
status"importing" | "queued" | "sending" | "paused" | "finished" | "cancelled"
createdAtstringISO 8601, UTC.
queuedintegerPeople queued (sent ones included).
skippedinteger
sentinteger
bouncedinteger
complainedinteger
unsubscribedintegerPeople who unsubscribed with this send’s link.
startedAtobject
nextWaveAtobjectSends go out in waves within sending hours, at the organization’s daily limit.
finishEstimatestring,null
pausedReasonobjectPaused by SealDrop’s safety stops; resuming needs acknowledged: true.

GET /v1/scheduled

Scheduled sends. Sends waiting for their time (made here or in the app).

Scope: sends:write.

curl https://api.sealdrop.ca/v1/scheduled \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
scheduledarray of object

DELETE /v1/scheduled/{id}

Cancel a scheduled send. It will not go out.

Scope: sends:write.

curl https://api.sealdrop.ca/v1/scheduled/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
okboolean

GET /v1/questionnaires/{id}

One questionnaire, with its questions. SurveyJS JSON, the subset SealDrop allows (text, comment, choices, dropdown, yes/no, date, signature).

Scope: forms:read.

curl https://api.sealdrop.ca/v1/questionnaires/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
questionCountinteger
updatedAtstringISO 8601, UTC.
surveyobjectThe questions, as SurveyJS JSON (the subset SealDrop allows).

POST /v1/questionnaires

Make a questionnaire. A name and its questions (SurveyJS JSON; anything outside SealDrop’s allowed subset is refused).

Scope: forms:write.

curl https://api.sealdrop.ca/v1/questionnaires \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
questionCountinteger
updatedAtstringISO 8601, UTC.
surveyobjectThe questions, as SurveyJS JSON (the subset SealDrop allows).

PUT /v1/questionnaires/{id}

Change a questionnaire. Requests already sent keep the copy they were sent with.

Scope: forms:write.

curl https://api.sealdrop.ca/v1/questionnaires/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
questionCountinteger
updatedAtstringISO 8601, UTC.
surveyobjectThe questions, as SurveyJS JSON (the subset SealDrop allows).

DELETE /v1/questionnaires/{id}

Delete a questionnaire. Requests already sent keep their copy.

Scope: forms:write.

curl https://api.sealdrop.ca/v1/questionnaires/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
okboolean

Open links. One link anyone can open to fill questionnaires and upload documents. The address is shown only when made or replaced.

Scope: forms:read.

curl https://api.sealdrop.ca/v1/open-links \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
openLinksarray of object

POST /v1/open-links

Make an open link. Within the plan’s limit. The answer holds its address (url) once.

Scope: forms:write.

curl https://api.sealdrop.ca/v1/open-links \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
templateIdsarray of string
allTemplatesboolean
modestring
filesAllowedboolean
filesRequiredboolean
notestring,null
perDayinteger
expiresOnstring,null
enabledboolean
todayintegerSubmissions today.
urlstring,nullOnly right after it is made or replaced — SealDrop keeps only a hash.
createdAtstringISO 8601, UTC.
updatedAtstringISO 8601, UTC.

Change an open link. Its questionnaires, documents, note, daily limit, last day, or turn it off (enabled: false).

Scope: forms:write.

curl https://api.sealdrop.ca/v1/open-links/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
templateIdsarray of string
allTemplatesboolean
modestring
filesAllowedboolean
filesRequiredboolean
notestring,null
perDayinteger
expiresOnstring,null
enabledboolean
todayintegerSubmissions today.
urlstring,nullOnly right after it is made or replaced — SealDrop keeps only a hash.
createdAtstringISO 8601, UTC.
updatedAtstringISO 8601, UTC.

POST /v1/open-links/{id}/rotate

Replace an open link’s address. The old address stops working; the new one is in the answer once.

Scope: forms:write.

curl https://api.sealdrop.ca/v1/open-links/{id}/rotate \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
idstring
namestring
templateIdsarray of string
allTemplatesboolean
modestring
filesAllowedboolean
filesRequiredboolean
notestring,null
perDayinteger
expiresOnstring,null
enabledboolean
todayintegerSubmissions today.
urlstring,nullOnly right after it is made or replaced — SealDrop keeps only a hash.
createdAtstringISO 8601, UTC.
updatedAtstringISO 8601, UTC.

Delete an open link. Its address stops working.

Scope: forms:write.

curl https://api.sealdrop.ca/v1/open-links/{id} \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
FieldTypeMeaning
okboolean

Errors

StatusCodeMeaning
400bad_requestThe request is malformed or a field is invalid.
400key_in_urlAn API key was found in the URL. Keys go only in the Authorization header; rotate any key that was put in a URL.
401invalid_keyThe key is missing, unknown, revoked or expired.
403ip_not_allowedThe key can't be used from this IP address (its allowlist).
403missing_scopeThe key doesn't have the scope this route needs.
403api_disabledThe API is turned off for this organization.
403organization_suspendedThe organization's account is suspended.
403organization_closedThe organization's account is closing or closed.
404not_foundNo such route or resource (or it belongs to another organization).
400idempotency_requiredThis call needs an Idempotency-Key header.
409idempotency_mismatchThis Idempotency-Key was already used with a different body.
409idempotency_in_progressA call with this Idempotency-Key is still being handled. Retry in a few seconds.
403test_keys_onlyOnly a test key can do this.
429test_daily_limitThe organization sent its test requests for today.
429daily_email_limitThe organization reached its daily email limit; the request wasn't sent.
403sms_not_enabledText messages are not on for this organization.
409duplicate_emailA contact with this email already exists; error.contactId is theirs.
409duplicate_phoneA contact with this mobile number already exists; error.contactId is theirs.
409duplicate_idNumberA contact with this client ID already exists; error.contactId is theirs.
400no_client_idThe organization hasn’t set up a client ID in Settings, so contacts can’t have one.
400no_mailThe email address's domain can't receive email.
409contact_limitThe organization has as many contacts as its plan allows.
409group_existsA group with this name already exists.
409group_limitThe organization has as many groups as it can.
403live_keys_onlyGroup sends reach real people, so only a live key can start one.
403not_on_planGroup sending isn't on the organization's plan.
403terms_requiredAn admin needs to accept the bulk-sending terms in the app first.
403list_lockedGroup sending is locked after automatic pauses until SealDrop reviews it.
409batch_activeAnother group send is still in progress.
429monthly_list_limitThe send would go past the organization's monthly bulk limit.
409nobodyNobody in the chosen groups can be sent to.
400acknowledge_requiredThis send was paused by a safety stop; resume with acknowledged: true after checking its results.
409open_link_limitThe organization has as many open links as its plan allows.
403live_access_requiredLive keys need SealDrop’s approval first: an admin requests it in Settings → Developers. Test keys work meanwhile.
429daily_text_limitThe organization reached its daily text limit; the text wasn't sent.
429number_text_limitThis mobile number already got today's texts from the organization; the text wasn't sent.
429resend_too_soonThis request was resent less than an hour ago. Wait for Retry-After seconds.
409resend_limitThis request was already resent 3 times. Cancel it and send a new request if needed.
429rate_limitedToo many requests. Wait for Retry-After seconds.
500internalSomething went wrong on our side. Retrying later is safe.
400invalid_requestOne or more fields are invalid; the message names them (never their values).