SealDrop Book a demo

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 optional image, showIf and inPdf. GET /v1/questionnaires/{id} returns them in place; POST and PUT /v1/questionnaires accept 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}/answers and questionCount leave it out, and the answers PDF shows it only when the organization ticked inPdf. 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: idNumber or clientNumber, as before.

Scores, calculations and flags in answers

  • GET /v1/requests/{id}/answers also returns scores (name, value and band), calculations (name and value) and flags (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}/answers it has "type": "matrix", and its value is a list of Item: Choice lines, 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}/answers as clientNumber; a questionnaire’s ID number stays idNumber.
  • When the page doesn’t ask for a name, the request’s person.name is an empty string: identify the person by clientNumber, idNumber or person.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 as d_ and its id (for example d_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 internal dv_dob) and idNumber. The organization’s own questions keep their q1, 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), source and sourceId (how they were added) and signup (their sign-up page answers). Requests: source and openLinkId.
  • 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}) counts unsubscribed; 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 titled New 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" in delivery). Resends: at most 3 per request, an hour apart (resend_too_soon with Retry-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 (with bulk and updatedSince), /v1/groups, /v1/sends, /v1/scheduled, /v1/questionnaires, /v1/open-links.
  • New events: request.sent, batch.finished, contact.unsubscribed. Errors duplicate_email and duplicate_phone carry the existing contactId.

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/requests with a required Idempotency-Key; /resend, /cancel, /filed.
  • Test keys (sd_test_): emails only to the key’s creator, no texts, and simulate-upload.

Reading requests, files and answers

  • /v1/requests, /v1/files/{id}/download (5-minute links to clean copies), /answers, /imported (then deleted), /v1/audit and /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.

← The API guide