Create a draft
Creates a draft. The PDF is attached separately (POST /v1/documents/{id}/file) and nothing is emailed until /send. With a templateId (public or owned), template fields are copied and — if no recipients were sent — template recipient slots are created with empty emails; template usageCount increments. An unresolvable templateId is a 400. Recipients passed here are created with status "pending".
View as MarkdownAuthorization
bearer In: header
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
curl -X POST "https://example.com/v1/documents" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "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": {} } ] }}List documents
Documents the caller can read: their own (active-org-scoped; legacy rows without org_id stay visible) plus any shared with the organization by a teammate. status/q/needsMe filter the page and `total`; counts/toSignCount/waitingCount/hasShared always describe the scope-only set, unaffected by status/q/needsMe/sort/limit/offset — same convention as Templates' `categories`, so switching tabs or typing a search never makes the other tabs' counts move. The result is paged only when limit or offset is sent; without either, every matching document is returned (as before this endpoint was paginated), up to 1000, and limit reports how many came back — total > that count means the list was cut off.
Live events (SSE)
A Server-Sent Events stream of live events for the caller. Today it carries file-conversion events, and further event types may be added, so clients must ignore event names they do not know. It tells the caller when a file they uploaded finishes converting to PDF (status "ready" or "failed"), replacing per-document polling. Scoped to the caller: only files on documents they own are reported, taken from the verified token. Frames carry ids and the new status only; re-read the document (GET /v1/documents/{id}) for the data. The stream emits `event: ready` once on connect (re-check any file you are waiting on — you may have missed an event while disconnected), then `event: conversion` with `{"documentId","fileId","status"}` as files settle, plus `: ping` heartbeat comments every 25s. The server ends the stream after 15 minutes; reconnect with a fresh token. Delivery is best-effort — keep a slow fallback poll of the document. Answers 503 when the server has no event listener; fall back to polling.