API reference
Base address: https://api.sealdrop.ca. Authentication: Authorization: Bearer sd_live_… (see the guide). Machine-readable: openapi.json and the Postman collection.
No route matches. Try a word like “file”, “group” or “send”.
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"
| Field | Type | Meaning |
|---|---|---|
organization | object | |
organization.id | string | The organization's id. |
organization.name | string | Its name, as its clients see it. |
organization.timeZone | string | IANA time zone, e.g. America/Toronto. All API times are UTC; use this to show them. |
key | object | |
key.id | string | The key's id (it appears in the organization's audit log). |
key.name | string | The name the admin gave the key. |
key.mode | "live" | "test" | test keys never email or text a real person. |
key.scopes | array 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.expiresAt | string | When the key stops working. ISO 8601, UTC. |
limits | object | |
limits.perMinute | integer | Calls per minute for this key. |
limits.perDay | integer | Calls 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"
| Field | Type | Meaning |
|---|---|---|
requests | array of object | |
nextCursor | string,null | Pass 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
reference | string | The 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. |
test | boolean | Made with a test key. Test keys see only test requests; live keys never see them. |
person | object | Who it was sent to, as entered (for an open link, as the person typed it). |
person.name | string | |
person.email | string,null | |
person.mobile | string,null | E.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. |
openLinkId | string,null | For open_link: which open link. |
channels | array of "email" | "sms" | |
note | string,null | The note shown to the person. |
message | string,null | The person's reply message, when replies were allowed. |
questionnaire | object | |
filesRequired | boolean | |
fileCount | integer | Files the person uploaded (not counting the answers PDF). |
blockedFiles | integer | Files deleted by the malware scan. |
createdAt | string | ISO 8601, UTC. |
submittedAt | string,null | ISO 8601, UTC, or null. |
linkExpiresAt | string | ISO 8601, UTC. |
deleteAt | string,null | When SealDrop deletes the files, if nobody does sooner. |
filesDeletedAt | string,null | ISO 8601, UTC, or null. |
importedAt | string,null | When a system confirmed it imported the documents (POST …/imported). |
files | array 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"
| Field | Type | Meaning |
|---|---|---|
url | string | A link to the clean copy. GET it within 5 minutes; no Authorization header. |
expiresAt | string | ISO 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"
| Field | Type | Meaning |
|---|---|---|
questionnaire | object | |
questionnaire.name | string | |
submittedAt | string | ISO 8601, UTC. |
answers | array of object | |
pdfFileId | string,null | The answers PDF among the request’s files. |
scores | array of object | The questionnaire’s own scores, worked out by SealDrop on submit (empty when it has none). |
calculations | array of object | The questionnaire’s calculations that have a value (ages, totals, formulas). |
flags | array of string | Why 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"
| Field | Type | Meaning |
|---|---|---|
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. |
request | object | |
request.id | string | |
request.reference | string | The 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.test | boolean | Made with a test key. Test keys see only test requests; live keys never see them. |
request.person | object | Who it was sent to, as entered (for an open link, as the person typed it). |
request.person.name | string | |
request.person.email | string,null | |
request.person.mobile | string,null | E.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.openLinkId | string,null | For open_link: which open link. |
request.channels | array of "email" | "sms" | |
request.note | string,null | The note shown to the person. |
request.message | string,null | The person's reply message, when replies were allowed. |
request.questionnaire | object | |
request.filesRequired | boolean | |
request.fileCount | integer | Files the person uploaded (not counting the answers PDF). |
request.blockedFiles | integer | Files deleted by the malware scan. |
request.createdAt | string | ISO 8601, UTC. |
request.submittedAt | string,null | ISO 8601, UTC, or null. |
request.linkExpiresAt | string | ISO 8601, UTC. |
request.deleteAt | string,null | When SealDrop deletes the files, if nobody does sooner. |
request.filesDeletedAt | string,null | ISO 8601, UTC, or null. |
request.importedAt | string,null | When 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"
| Field | Type | Meaning |
|---|---|---|
events | array of object | |
nextCursor | string,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"
| Field | Type | Meaning |
|---|---|---|
events | array of object | |
nextCursor | string,null | Pass 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"
| Field | Type | Meaning |
|---|---|---|
request | object | |
request.id | string | |
request.reference | string | The 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.test | boolean | Made with a test key. Test keys see only test requests; live keys never see them. |
request.person | object | Who it was sent to, as entered (for an open link, as the person typed it). |
request.person.name | string | |
request.person.email | string,null | |
request.person.mobile | string,null | E.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.openLinkId | string,null | For open_link: which open link. |
request.channels | array of "email" | "sms" | |
request.note | string,null | The note shown to the person. |
request.message | string,null | The person's reply message, when replies were allowed. |
request.questionnaire | object | |
request.filesRequired | boolean | |
request.fileCount | integer | Files the person uploaded (not counting the answers PDF). |
request.blockedFiles | integer | Files deleted by the malware scan. |
request.createdAt | string | ISO 8601, UTC. |
request.submittedAt | string,null | ISO 8601, UTC, or null. |
request.linkExpiresAt | string | ISO 8601, UTC. |
request.deleteAt | string,null | When SealDrop deletes the files, if nobody does sooner. |
request.filesDeletedAt | string,null | ISO 8601, UTC, or null. |
request.importedAt | string,null | When a system confirmed it imported the documents (POST …/imported). |
delivery | object | Per 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"
| Field | Type | Meaning |
|---|---|---|
request | object | |
request.id | string | |
request.reference | string | The 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.test | boolean | Made with a test key. Test keys see only test requests; live keys never see them. |
request.person | object | Who it was sent to, as entered (for an open link, as the person typed it). |
request.person.name | string | |
request.person.email | string,null | |
request.person.mobile | string,null | E.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.openLinkId | string,null | For open_link: which open link. |
request.channels | array of "email" | "sms" | |
request.note | string,null | The note shown to the person. |
request.message | string,null | The person's reply message, when replies were allowed. |
request.questionnaire | object | |
request.filesRequired | boolean | |
request.fileCount | integer | Files the person uploaded (not counting the answers PDF). |
request.blockedFiles | integer | Files deleted by the malware scan. |
request.createdAt | string | ISO 8601, UTC. |
request.submittedAt | string,null | ISO 8601, UTC, or null. |
request.linkExpiresAt | string | ISO 8601, UTC. |
request.deleteAt | string,null | When SealDrop deletes the files, if nobody does sooner. |
request.filesDeletedAt | string,null | ISO 8601, UTC, or null. |
request.importedAt | string,null | When a system confirmed it imported the documents (POST …/imported). |
delivery | object | Per 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"
| Field | Type | Meaning |
|---|---|---|
request | object | |
request.id | string | |
request.reference | string | The 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.test | boolean | Made with a test key. Test keys see only test requests; live keys never see them. |
request.person | object | Who it was sent to, as entered (for an open link, as the person typed it). |
request.person.name | string | |
request.person.email | string,null | |
request.person.mobile | string,null | E.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.openLinkId | string,null | For open_link: which open link. |
request.channels | array of "email" | "sms" | |
request.note | string,null | The note shown to the person. |
request.message | string,null | The person's reply message, when replies were allowed. |
request.questionnaire | object | |
request.filesRequired | boolean | |
request.fileCount | integer | Files the person uploaded (not counting the answers PDF). |
request.blockedFiles | integer | Files deleted by the malware scan. |
request.createdAt | string | ISO 8601, UTC. |
request.submittedAt | string,null | ISO 8601, UTC, or null. |
request.linkExpiresAt | string | ISO 8601, UTC. |
request.deleteAt | string,null | When SealDrop deletes the files, if nobody does sooner. |
request.filesDeletedAt | string,null | ISO 8601, UTC, or null. |
request.importedAt | string,null | When 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"
| Field | Type | Meaning |
|---|---|---|
request | object | |
request.id | string | |
request.reference | string | The 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.test | boolean | Made with a test key. Test keys see only test requests; live keys never see them. |
request.person | object | Who it was sent to, as entered (for an open link, as the person typed it). |
request.person.name | string | |
request.person.email | string,null | |
request.person.mobile | string,null | E.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.openLinkId | string,null | For open_link: which open link. |
request.channels | array of "email" | "sms" | |
request.note | string,null | The note shown to the person. |
request.message | string,null | The person's reply message, when replies were allowed. |
request.questionnaire | object | |
request.filesRequired | boolean | |
request.fileCount | integer | Files the person uploaded (not counting the answers PDF). |
request.blockedFiles | integer | Files deleted by the malware scan. |
request.createdAt | string | ISO 8601, UTC. |
request.submittedAt | string,null | ISO 8601, UTC, or null. |
request.linkExpiresAt | string | ISO 8601, UTC. |
request.deleteAt | string,null | When SealDrop deletes the files, if nobody does sooner. |
request.filesDeletedAt | string,null | ISO 8601, UTC, or null. |
request.importedAt | string,null | When 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"
| Field | Type | Meaning |
|---|---|---|
questionnaires | array 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"
| Field | Type | Meaning |
|---|---|---|
designs | array 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"
| Field | Type | Meaning |
|---|---|---|
request | object | |
request.id | string | |
request.reference | string | The 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.test | boolean | Made with a test key. Test keys see only test requests; live keys never see them. |
request.person | object | Who it was sent to, as entered (for an open link, as the person typed it). |
request.person.name | string | |
request.person.email | string,null | |
request.person.mobile | string,null | E.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.openLinkId | string,null | For open_link: which open link. |
request.channels | array of "email" | "sms" | |
request.note | string,null | The note shown to the person. |
request.message | string,null | The person's reply message, when replies were allowed. |
request.questionnaire | object | |
request.filesRequired | boolean | |
request.fileCount | integer | Files the person uploaded (not counting the answers PDF). |
request.blockedFiles | integer | Files deleted by the malware scan. |
request.createdAt | string | ISO 8601, UTC. |
request.submittedAt | string,null | ISO 8601, UTC, or null. |
request.linkExpiresAt | string | ISO 8601, UTC. |
request.deleteAt | string,null | When SealDrop deletes the files, if nobody does sooner. |
request.filesDeletedAt | string,null | ISO 8601, UTC, or null. |
request.importedAt | string,null | When 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"
| Field | Type | Meaning |
|---|---|---|
contacts | array of object | |
deleted | array of string | With updatedSince: ids deleted since then. |
nextCursor | string,null | |
asOf | string | Pass 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
email | string,null | |
mobile | string,null | E.164, e.g. +16045550123. |
dateOfBirth | string,null | YYYY-MM-DD, when known: entered by staff, given on a sign-up page or an open link’s questionnaire, or set through the API. |
idNumber | string,null | The 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. |
sourceId | string,null | For signup_page and open_link: which page or link. |
signup | object | What they answered on a sign-up page — their latest sign-up. |
groupIds | array of string | |
doNotContact | boolean | They unsubscribed or staff marked them: no bulk requests. |
emailStatus | "ok" | "bounced" | "complained" | |
lastActivityAt | string | ISO 8601, UTC. |
deleteOn | string | YYYY-MM-DD: deleted automatically after 24 months without activity. |
createdAt | string | ISO 8601, UTC. |
updatedAt | string | ISO 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
email | string,null | |
mobile | string,null | E.164, e.g. +16045550123. |
dateOfBirth | string,null | YYYY-MM-DD, when known: entered by staff, given on a sign-up page or an open link’s questionnaire, or set through the API. |
idNumber | string,null | The 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. |
sourceId | string,null | For signup_page and open_link: which page or link. |
signup | object | What they answered on a sign-up page — their latest sign-up. |
groupIds | array of string | |
doNotContact | boolean | They unsubscribed or staff marked them: no bulk requests. |
emailStatus | "ok" | "bounced" | "complained" | |
lastActivityAt | string | ISO 8601, UTC. |
deleteOn | string | YYYY-MM-DD: deleted automatically after 24 months without activity. |
createdAt | string | ISO 8601, UTC. |
updatedAt | string | ISO 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"
| Field | Type | Meaning |
|---|---|---|
results | array of object | |
created | integer | |
updated | integer | |
skipped | integer |
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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
email | string,null | |
mobile | string,null | E.164, e.g. +16045550123. |
dateOfBirth | string,null | YYYY-MM-DD, when known: entered by staff, given on a sign-up page or an open link’s questionnaire, or set through the API. |
idNumber | string,null | The 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. |
sourceId | string,null | For signup_page and open_link: which page or link. |
signup | object | What they answered on a sign-up page — their latest sign-up. |
groupIds | array of string | |
doNotContact | boolean | They unsubscribed or staff marked them: no bulk requests. |
emailStatus | "ok" | "bounced" | "complained" | |
lastActivityAt | string | ISO 8601, UTC. |
deleteOn | string | YYYY-MM-DD: deleted automatically after 24 months without activity. |
createdAt | string | ISO 8601, UTC. |
updatedAt | string | ISO 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"
| Field | Type | Meaning |
|---|---|---|
ok | boolean |
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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
email | string,null | |
mobile | string,null | E.164, e.g. +16045550123. |
dateOfBirth | string,null | YYYY-MM-DD, when known: entered by staff, given on a sign-up page or an open link’s questionnaire, or set through the API. |
idNumber | string,null | The 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. |
sourceId | string,null | For signup_page and open_link: which page or link. |
signup | object | What they answered on a sign-up page — their latest sign-up. |
groupIds | array of string | |
doNotContact | boolean | They unsubscribed or staff marked them: no bulk requests. |
emailStatus | "ok" | "bounced" | "complained" | |
lastActivityAt | string | ISO 8601, UTC. |
deleteOn | string | YYYY-MM-DD: deleted automatically after 24 months without activity. |
createdAt | string | ISO 8601, UTC. |
updatedAt | string | ISO 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"
| Field | Type | Meaning |
|---|---|---|
groups | array 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
colour | "teal" | "blue" | "violet" | "pink" | "orange" | "amber" | "green" | "grey" | |
createdAt | string | ISO 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
colour | "teal" | "blue" | "violet" | "pink" | "orange" | "amber" | "green" | "grey" | |
createdAt | string | ISO 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"
| Field | Type | Meaning |
|---|---|---|
ok | boolean |
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"
| Field | Type | Meaning |
|---|---|---|
updated | integer |
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"
| Field | Type | Meaning |
|---|---|---|
status | "started" | "scheduled" | |
send | object | When started now. |
queued | object | |
skipped | object | People skipped: no email, don’t contact, bounced or reported before, sent too recently. |
scheduled | object | When 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"
| Field | Type | Meaning |
|---|---|---|
sends | array 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
status | "importing" | "queued" | "sending" | "paused" | "finished" | "cancelled" | |
createdAt | string | ISO 8601, UTC. |
queued | integer | People queued (sent ones included). |
skipped | integer | |
sent | integer | |
bounced | integer | |
complained | integer | |
unsubscribed | integer | People who unsubscribed with this send’s link. |
startedAt | object | |
nextWaveAt | object | Sends go out in waves within sending hours, at the organization’s daily limit. |
finishEstimate | string,null | |
pausedReason | object | Paused 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"
| Field | Type | Meaning |
|---|---|---|
send | object | |
send.id | string | |
send.status | "importing" | "queued" | "sending" | "paused" | "finished" | "cancelled" | |
send.createdAt | string | ISO 8601, UTC. |
send.queued | integer | People queued (sent ones included). |
send.skipped | integer | |
send.sent | integer | |
send.bounced | integer | |
send.complained | integer | |
send.unsubscribed | integer | People who unsubscribed with this send’s link. |
send.startedAt | object | |
send.nextWaveAt | object | Sends go out in waves within sending hours, at the organization’s daily limit. |
send.finishEstimate | string,null | |
send.pausedReason | object | Paused by SealDrop’s safety stops; resuming needs acknowledged: true. |
people | array 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
status | "importing" | "queued" | "sending" | "paused" | "finished" | "cancelled" | |
createdAt | string | ISO 8601, UTC. |
queued | integer | People queued (sent ones included). |
skipped | integer | |
sent | integer | |
bounced | integer | |
complained | integer | |
unsubscribed | integer | People who unsubscribed with this send’s link. |
startedAt | object | |
nextWaveAt | object | Sends go out in waves within sending hours, at the organization’s daily limit. |
finishEstimate | string,null | |
pausedReason | object | Paused 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
status | "importing" | "queued" | "sending" | "paused" | "finished" | "cancelled" | |
createdAt | string | ISO 8601, UTC. |
queued | integer | People queued (sent ones included). |
skipped | integer | |
sent | integer | |
bounced | integer | |
complained | integer | |
unsubscribed | integer | People who unsubscribed with this send’s link. |
startedAt | object | |
nextWaveAt | object | Sends go out in waves within sending hours, at the organization’s daily limit. |
finishEstimate | string,null | |
pausedReason | object | Paused 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
status | "importing" | "queued" | "sending" | "paused" | "finished" | "cancelled" | |
createdAt | string | ISO 8601, UTC. |
queued | integer | People queued (sent ones included). |
skipped | integer | |
sent | integer | |
bounced | integer | |
complained | integer | |
unsubscribed | integer | People who unsubscribed with this send’s link. |
startedAt | object | |
nextWaveAt | object | Sends go out in waves within sending hours, at the organization’s daily limit. |
finishEstimate | string,null | |
pausedReason | object | Paused 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"
| Field | Type | Meaning |
|---|---|---|
scheduled | array 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"
| Field | Type | Meaning |
|---|---|---|
ok | boolean |
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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
questionCount | integer | |
updatedAt | string | ISO 8601, UTC. |
survey | object | The 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
questionCount | integer | |
updatedAt | string | ISO 8601, UTC. |
survey | object | The 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
questionCount | integer | |
updatedAt | string | ISO 8601, UTC. |
survey | object | The 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"
| Field | Type | Meaning |
|---|---|---|
ok | boolean |
GET /v1/open-links
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"
| Field | Type | Meaning |
|---|---|---|
openLinks | array 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
templateIds | array of string | |
allTemplates | boolean | |
mode | string | |
filesAllowed | boolean | |
filesRequired | boolean | |
note | string,null | |
perDay | integer | |
expiresOn | string,null | |
enabled | boolean | |
today | integer | Submissions today. |
url | string,null | Only right after it is made or replaced — SealDrop keeps only a hash. |
createdAt | string | ISO 8601, UTC. |
updatedAt | string | ISO 8601, UTC. |
PUT /v1/open-links/{id}
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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
templateIds | array of string | |
allTemplates | boolean | |
mode | string | |
filesAllowed | boolean | |
filesRequired | boolean | |
note | string,null | |
perDay | integer | |
expiresOn | string,null | |
enabled | boolean | |
today | integer | Submissions today. |
url | string,null | Only right after it is made or replaced — SealDrop keeps only a hash. |
createdAt | string | ISO 8601, UTC. |
updatedAt | string | ISO 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"
| Field | Type | Meaning |
|---|---|---|
id | string | |
name | string | |
templateIds | array of string | |
allTemplates | boolean | |
mode | string | |
filesAllowed | boolean | |
filesRequired | boolean | |
note | string,null | |
perDay | integer | |
expiresOn | string,null | |
enabled | boolean | |
today | integer | Submissions today. |
url | string,null | Only right after it is made or replaced — SealDrop keeps only a hash. |
createdAt | string | ISO 8601, UTC. |
updatedAt | string | ISO 8601, UTC. |
DELETE /v1/open-links/{id}
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"
| Field | Type | Meaning |
|---|---|---|
ok | boolean |
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | The request is malformed or a field is invalid. |
| 400 | key_in_url | An API key was found in the URL. Keys go only in the Authorization header; rotate any key that was put in a URL. |
| 401 | invalid_key | The key is missing, unknown, revoked or expired. |
| 403 | ip_not_allowed | The key can't be used from this IP address (its allowlist). |
| 403 | missing_scope | The key doesn't have the scope this route needs. |
| 403 | api_disabled | The API is turned off for this organization. |
| 403 | organization_suspended | The organization's account is suspended. |
| 403 | organization_closed | The organization's account is closing or closed. |
| 404 | not_found | No such route or resource (or it belongs to another organization). |
| 400 | idempotency_required | This call needs an Idempotency-Key header. |
| 409 | idempotency_mismatch | This Idempotency-Key was already used with a different body. |
| 409 | idempotency_in_progress | A call with this Idempotency-Key is still being handled. Retry in a few seconds. |
| 403 | test_keys_only | Only a test key can do this. |
| 429 | test_daily_limit | The organization sent its test requests for today. |
| 429 | daily_email_limit | The organization reached its daily email limit; the request wasn't sent. |
| 403 | sms_not_enabled | Text messages are not on for this organization. |
| 409 | duplicate_email | A contact with this email already exists; error.contactId is theirs. |
| 409 | duplicate_phone | A contact with this mobile number already exists; error.contactId is theirs. |
| 409 | duplicate_idNumber | A contact with this client ID already exists; error.contactId is theirs. |
| 400 | no_client_id | The organization hasn’t set up a client ID in Settings, so contacts can’t have one. |
| 400 | no_mail | The email address's domain can't receive email. |
| 409 | contact_limit | The organization has as many contacts as its plan allows. |
| 409 | group_exists | A group with this name already exists. |
| 409 | group_limit | The organization has as many groups as it can. |
| 403 | live_keys_only | Group sends reach real people, so only a live key can start one. |
| 403 | not_on_plan | Group sending isn't on the organization's plan. |
| 403 | terms_required | An admin needs to accept the bulk-sending terms in the app first. |
| 403 | list_locked | Group sending is locked after automatic pauses until SealDrop reviews it. |
| 409 | batch_active | Another group send is still in progress. |
| 429 | monthly_list_limit | The send would go past the organization's monthly bulk limit. |
| 409 | nobody | Nobody in the chosen groups can be sent to. |
| 400 | acknowledge_required | This send was paused by a safety stop; resume with acknowledged: true after checking its results. |
| 409 | open_link_limit | The organization has as many open links as its plan allows. |
| 403 | live_access_required | Live keys need SealDrop’s approval first: an admin requests it in Settings → Developers. Test keys work meanwhile. |
| 429 | daily_text_limit | The organization reached its daily text limit; the text wasn't sent. |
| 429 | number_text_limit | This mobile number already got today's texts from the organization; the text wasn't sent. |
| 429 | resend_too_soon | This request was resent less than an hour ago. Wait for Retry-After seconds. |
| 409 | resend_limit | This request was already resent 3 times. Cancel it and send a new request if needed. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 500 | internal | Something went wrong on our side. Retrying later is safe. |
| 400 | invalid_request | One or more fields are invalid; the message names them (never their values). |