Document requests: ask recipients to return files

This entry describes the v1 contract. Document requests survive into Sender API v2 as an upload question on a form correspondence: ref rather than field_id, answers read from GET /correspondence/{id}/responses, files from …/responses/{participant_id}/documents/{field_ref}, and verification at POST /verify. See Collecting responses.

Forms can now collect documents, not just answers. Add a document field to a template and it becomes a document request: the recipient returns a file (a bank statement for a visa application, a CAC certificate, a utility bill), sealed and verifiable on the way back.

What's new

  • A document field type: takes the usual field_id / label / required, plus optional accepted_media (narrow the file types) and guidance (per-field instructions). One document per field; a document field can be a conditional target of a choice field's branching.
  • Delivered as document_request, with disclosure baked in: because collecting documents is a data collection under the NDPA, the delivery attributes must declare purpose and retention_note alongside the form_id. The recipient sees them before attaching anything.
  • A sealed return document: every submission produces a deterministic PDF cover carrying the answers, a per-file provenance manifest, and a receipt code, verifiable at /public/verify. Download the cover from …/responses/{response_id}/document and each file from …/documents/{field_id}. Provenance is stated in plain language: recipient_upload is the recipient's own attestation, never a Keepable verification of the contents.
  • Decline is first-class: a recipient can refuse. The response comes back status: "declined" with an optional decline_reason, and nothing is disclosed: "asked and refused" is itself evidence.
  • Chase who still owes you: a response-tracking roster (GET …/forms/{form_id}/recipients) marks each recipient pending, submitted, or declined, and POST …/forms/{form_id}/remind nudges only the pending ones (idempotent per recipient per day).

document_request is a preview content type; its shape may still change. See Forms for the full walkthrough.

Back to every dated change.