API changelog
Every path starts with /v1. We add fields, routes and event types without a new version — ignore what you don't know. Anything that would break an integration gets a new version, announced at least 12 months ahead, and /v1 keeps working until then.
Text blocks in questionnaires
- A questionnaire can now have text blocks among its questions (an agreement, instructions, a logo):
{"type": "textblock", "name": "t1", "doc": …}, with an optionalimage,showIfandinPdf.GET /v1/questionnaires/{id}returns them in place;POSTandPUT /v1/questionnairesaccept them, checked like the app (the document is formatted text only, never HTML; an image must already be in the organization’s image library). - A text block is never an answer:
GET /v1/requests/{id}/answersandquestionCountleave it out, and the answers PDF shows it only when the organization tickedinPdf. Other fields are unchanged.
The client ID on contacts
- A contact has
idNumber: the organization’s client ID (a government-issued number or its own, set in Settings), whole. Set it on create, update and bulk create; it’s checked by the organization’s rules (invalid:idNumber) and belongs to one client only (duplicate_idNumber, 409).no_client_id(400) when the organization hasn’t set one. Staff see it masked in the app. - A sign-up answer to a question the organization marked Sensitive has
"sensitive": true; the value is whole here. - In answers, the client ID keeps its names:
idNumberorclientNumber, as before.
Scores, calculations and flags in answers
GET /v1/requests/{id}/answersalso returnsscores(name, value and band),calculations(name and value) andflags(the organization’s reasons for review), as SealDrop worked them out on submit. Empty lists when the questionnaire has none. Other fields are unchanged.
Rating grids in answers
- A questionnaire can now have a rating grid (one scale for many items). In
GET /v1/requests/{id}/answersit has"type": "matrix", and itsvalueis a list ofItem: Choicelines, one per item answered. Other answers are unchanged.
Open links: your own fields
- An open link’s page can ask for an ID instead of (or as well as) a name. The organization’s own number arrives in
GET /v1/requests/{id}/answersasclientNumber; a questionnaire’s ID number staysidNumber. - When the page doesn’t ask for a name, the request’s
person.nameis an empty string: identify the person byclientNumber,idNumberorperson.email.
Open links with their own page
- An open link can now ask for a date of birth and a few questions of its own before the person continues. They arrive with the questionnaire’s answers in
GET /v1/requests/{id}/answers:dateOfBirth, and each of the link’s questions asd_and its id (for exampled_qk3j2a), which never changes. A documents-only link with such questions has answers too. - The page’s design is made in the app;
PUT /v1/open-links/{id}leaves it as it is.
Matching people to your records
- Answers name fixed fields the same everywhere:
dateOfBirth(was the internaldv_dob) andidNumber. The organization’s own questions keep theirq1,q2… for good — moving or rewording questions no longer renumbers them, and a removed question’s name is never reused. - Contacts:
dateOfBirth(read, create, update, bulk),sourceandsourceId(how they were added) andsignup(their sign-up page answers). Requests:sourceandopenLinkId. - New event
contact.created(id only), also for webhooks. How it fits together: “Matching people to your records” in the API guide.
Unsubscribes in group-send results
- A group send (
GET /v1/sends/{id}) countsunsubscribed; in its results a person who unsubscribed with that email’s link shows"status": "unsubscribed"(unless they sent documents anyway).
Email subjects and resends
- Request emails end their subject with a short code (the first 6 characters of
reference), so each request is its own email conversation; reminders too. Organizations can turn it off. - A resend (
POST /v1/requests/{id}/resend) is titledNew link: …and says the earlier link no longer works.
Live keys by approval, and sending limits
- New live keys need SealDrop’s approval (an admin requests it in Settings → Developers); live keys already in use keep working. Refused:
403 live_access_required. - Texts: at most 5 a day to one number and the organization’s daily text limit (
number_text_limit,daily_text_limit;"sms": "number_limit"/"daily_text_limit"indelivery). Resends: at most 3 per request, an hour apart (resend_too_soonwithRetry-After,resend_limit). The same limits apply in the app.
Guides, Postman and the Developers quick start
- Step-by-step guides for pulling documents, sending requests and group sends, in curl, JavaScript and Python — every sample tested against the API.
- A Postman collection; this changelog; search in the reference.
- In the app, Settings → Developers shows the plan’s limits, a one-step test key and the last 7 days of calls and errors.
Contacts, groups, group sends and forms
- 30 new routes:
/v1/contacts(withbulkandupdatedSince),/v1/groups,/v1/sends,/v1/scheduled,/v1/questionnaires,/v1/open-links. - New events:
request.sent,batch.finished,contact.unsubscribed. Errorsduplicate_emailandduplicate_phonecarry the existingcontactId.
Webhooks
- Signed (
SealDrop-Signature), ids-only notifications to HTTPS endpoints the organization’s admins add; retried for 24 hours.
Sending requests and test mode
POST /v1/requestswith a requiredIdempotency-Key;/resend,/cancel,/filed.- Test keys (
sd_test_): emails only to the key’s creator, no texts, andsimulate-upload.
Reading requests, files and answers
/v1/requests,/v1/files/{id}/download(5-minute links to clean copies),/answers,/imported(then deleted),/v1/auditand/v1/events.
API keys
- Live and test keys made by admins, stored only as hashes; scopes, IP allowlists, expiry, a new secret with 24 hours’ overlap;
GET /v1/me.