Send Document For Signing

Upload a PDF and send it for signing immediately — or leave it as a Draft for human review.

• file: one PDF. Keep this for existing callers. Combined with files when both are sent; order is file first, then files.
• files: repeating extra PDF parts. Accepted together with file. Cap is MAX_ENVELOPE_DOCUMENTS (default 10) and MAX_COMBINED_BYTES from MAX_PDF_SIZE_MB.
• document_names: optional JSON array of display names aligned to file first, then files.
• recipients: JSON array of recipient objects with name, email, and role. Required when sending; optional when draft=true / auto_send=false.
• name: Optional document name
• sequential: Optional boolean (multipart string). Default true: recipients sign one at a time in list order. Set false so everyone can sign at once. This is the sequential send-body flag.
• metadata: Optional JSON object of opaque integrator context, echoed into data.metadata on every webhook for this envelope. Flat string->string only. Use it to carry your own join key -- document_id is NOT stable for this purpose, because document.completed reports the id of the COMPLETED document, not the original. Example: {"deal_id": "d_123", "stage": "contract_out"}
• auto_send: default true. Set false to create a Draft (no credit debit, no invites). Existing callers that omit this still send.
• draft: true is the same as auto_send=false and wins if both are set, so draft mode cannot accidentally send.
• fields: optional JSON array of placed fields (same shape as PUT /api/v1/documents/drafts/{id}/fields). Used only in draft mode.
• prefill: optional JSON object of per-send text values keyed by field "party:name", e.g. {"client:company": "Acme Inc"}. Sets or overrides that text field's default_value for this send only. Unknown or non-text keys are a 422 invalid_prefill_key. Not accepted in draft mode: set fields[].default_value instead.
• Idempotency-Key header: optional. When set on a send (not draft), the server claims (org, v1.documents.send, key) before the credit debit. A retry with the same key and byte-identical inputs replays the stored response; the same key with different inputs is a 409; a concurrent in-flight request with the same key is a 409 with Retry-After. A send interrupted mid-flight becomes retakable after ten minutes.

Example recipients:

[
    {"name": "John Doe", "email": "john@example.com", "role": "employee"},
    {"name": "Jane Smith", "email": "jane@example.com", "role": "manager"}
]

Rate limit: 100 requests per hour per API key