Add a recipient, or a signer-group slot, to a draft
An individual recipient (the default) needs an email. Setting isGroup true (EAS-125) instead creates a signer-group slot — one signing slot any of several people can satisfy — which starts with no email and no members; members are added with POST .../recipients/{rid}/members, and at least one is required before the document can be sent. A group's role must be "signer".
View as MarkdownAuthorization
bearer In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/documents/string/recipients" \ -H "Content-Type: application/json" \ -d '{}'{ "document": { "id": "string", "name": "string", "url": "string", "status": "string", "created": "2019-08-24T14:15:22Z", "modified": "2019-08-24T14:15:22Z", "size": 0, "pages": 0, "templateId": "string", "hasFile": true, "hasFinalFile": true, "files": [ { "id": "string", "name": "string", "position": 0, "size": 0, "pages": 0, "created": "2019-08-24T14:15:22Z", "status": "ready", "conversionError": "string" } ], "signingMode": "string", "message": "string", "sentAt": "2019-08-24T14:15:22Z", "completedAt": "2019-08-24T14:15:22Z", "voidedAt": "2019-08-24T14:15:22Z", "voidReason": "string", "declinedAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "autoRemindDays": 0, "lastRemindedAt": "2019-08-24T14:15:22Z", "legalHold": true, "scheduledPurgeAt": "2019-08-24T14:15:22Z", "visibility": "string", "ownerId": "string", "requiresNotarization": true, "notaryState": "string", "recipients": [ { "id": "string", "name": "string", "email": "string", "role": "string", "status": "string", "orderIndex": 0, "signedAt": "2019-08-24T14:15:22Z", "viewedAt": "2019-08-24T14:15:22Z", "declinedAt": "2019-08-24T14:15:22Z", "declineReason": "string", "hasAccessCode": true, "verificationMethod": "none", "signature": "string", "isGroup": true, "groupLabel": "string", "signedByName": "string", "signedByEmail": "string", "members": [ { "id": "string", "name": "string", "email": "string", "viewedAt": "2019-08-24T14:15:22Z", "declinedAt": "2019-08-24T14:15:22Z" } ], "reassignedFromName": "string", "reassignedFromEmail": "string", "reassignReason": "string", "reassignedAt": "2019-08-24T14:15:22Z" } ], "fields": [ { "id": "string", "type": "signature", "x": 0, "y": 0, "width": 0, "height": 0, "page": 0, "required": true, "label": "string", "value": "string", "recipientId": "string", "fileId": "string", "config": {} } ] }}Reorder a draft's file collection (EAS-114)
Body lists every current file id exactly once, in the new order — the same order files are stamped, merged, and rendered in. Drafts only.
Update a recipient on a draft, or correct one on a pending document
On a draft, the usual full edit (name, email, role, order, access code). On a pending document, only name and email may be corrected, and only for a recipient who hasn't signed yet — role, order, access code, and isGroup are structural, draft-only settings. Correcting email invalidates that recipient's current signing link (only theirs; every other recipient's token lives on their own row) and emails them a fresh one. Every correction is recorded in the document's audit trail with what changed. A correction can change a name but never blank it (a group slot always needs one too; only a draft individual may be nameless), and on a pending document cannot move a recipient onto an address another individual recipient already has, and once a payment has started on the slot the email cannot change at all (409 email_blocked_payment), because the charge belongs to the person who started it. Re-casing a recipient's own address is not a correction: it changes nothing and issues no new link. Names refuse control characters and invisible formatting characters (bidi overrides, zero-width space). Draft-only, isGroup true additionally converts an individual slot that has no email yet into a signer group (name becomes its label) — one-way, and only while the slot is still unaddressed; a group can't be converted back.