Documents

GET /v1/documents

List Documents

Query

• status string | null
• folder string (uuid) | null
• q string (max length 200) | null
• sort string default "created"
• batch string (uuid) | null. A bulk send id: list only its member documents. Without it, members of bulk sends are hidden (the batch is the first-class object, BS-4).
• limit integer (>= 1, <= 200) default 50
• offset integer (>= 0, <= 9223372036854776000) default 0

Responses

• 200 DocumentPage (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/documents

Create Document

Create a document in one call: a `multipart/form-data` request with two parts. `document` is the JSON body (title, recipients, fields and settings), sent as a part of type `application/json` or as a plain form field. `file` is the PDF, at most 50 MB. The answer is the draft, with its recipient and field ids, ready to read, change, send or delete. Everything is checked in this call, and a refusal creates nothing: a body that is not this form, or a missing, repeated or unknown part, is a 422 `request-invalid` naming it; a bad `document` part is a 422 `request-invalid` naming the member; an empty file, anything that is not a PDF, a damaged PDF, a password-protected PDF, one with no pages, or a field placed off its pages is a 422 `validation-failed` whose `detail` says which; more than 50 MB is a 422 `pdf-too-large`. The `Content-Type` of the file part is not consulted; the bytes are. (Register: D180, ADR 0078.) curl https://api.signenvoy.com/v1/documents \ -H "Authorization: Bearer $SIGNENVOY_API_KEY" \ -F 'document={"title":"NDA","recipients":[...]};type=application/json' \ -F file=@nda.pdf

Request body (multipart/form-data, required)

Responses

• 201 DocumentOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

GET /v1/documents/{doc_id}

Get Document

Read a document. Every response carries an `ETag`; send it back as `If-None-Match` and an unchanged document answers 304. While the document can still change on its own, responses advise `X-SignEnvoy-Poll-Interval: 30` and link the webhook docs: prefer the `document.completed` and `document.sealed` webhooks to reading on a timer. One key may read one document 10 times at once, then once every 15 seconds (429 `polling-too-fast` beyond). `doc_id` may also be the Reference printed on the Certificate of Completion (`env_…`) or the UUID in it; the response carries the `doc_…` id.

Path

• doc_id string

Query

• wait integer (>= 1, <= 30) | null. Long poll: hold the request up to this many seconds (1–30) until the document differs from the version named in `If-None-Match` (or from the version at the start of the request), then answer 200. At the deadline the answer is 304 when `If-None-Match` still matches, otherwise 200. Prefer webhooks; see /guides/polling.

Headers

• if-none-match string | null. An `ETag` from an earlier read. A match is a 304 with no body.

Responses

• 200 DocumentOut (application/json): Successful Response
• 304 no body: Not Modified: `If-None-Match` matched the current `ETag`. No body.
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/polling-too-fast when one key reads one document more than 10 times at once, then faster than once every 15 s; /problems/rate-limited for the workspace limit or more than 10 concurrent `wait` reads. Retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

PATCH /v1/documents/{doc_id}

Patch Document

Path

• doc_id string

Request body (application/json, required)

Responses

• 200 DocumentOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

DELETE /v1/documents/{doc_id}

Delete Document

Permanently delete a document. Allowed while the document's `status` is `draft`, `voided`, `expired`, `completed`, or `rejected`. Deletion removes the document, its recipients, its fields, its activity record, and its stored PDFs, including the sealed PDF and its certificate; the id then answers 404 everywhere. It cannot be undone: download a completed document first if you need to keep it. Sent and partially signed documents cannot be deleted (409 `invalid-state`): void the document first, then delete it. Deleting a document does not change this month's usage count. (Register: D87, ADR 0018; D122, ADR 0033.)

Path

• doc_id string

Responses

• 204 no body: Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): /problems/invalid-state: only draft, voided, and expired documents can be deleted.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

GET /v1/documents/{doc_id}/download

Download Document

Path

• doc_id string

Query

• variant string default "signed"

Responses

• 200 string (binary) (application/pdf): PDF bytes
• 307 no body: Redirect to a short-lived artifact URL
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): /problems/not-found, or /problems/not-ready when the artifact is not yet available.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/documents/{doc_id}/duplicate

Duplicate Document

T-5 "use as new" (D54): a fresh draft from the original PDF with the same recipients, fields, and display preferences. No signing links exist until it is sent; nothing is emailed.

Path

• doc_id string

Request body (application/json)

Type: DuplicateDocumentIn | null

Responses

• 201 DocumentOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

GET /v1/documents/{doc_id}/events

Document Events

Path

• doc_id string

Query

• after_seq integer (>= 0, <= 2147483647) default 0

Responses

• 200 array of EventOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

PUT /v1/documents/{doc_id}/fields

Put Fields

Path

• doc_id string

Request body (application/json, required)

Type: array of FieldSpec

Responses

• 200 array of FieldOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

PUT /v1/documents/{doc_id}/recipients

Put Recipients

Path

• doc_id string

Request body (application/json, required)

Type: array of RecipientSpec

Responses

• 200 array of RecipientOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/documents/{doc_id}/recipients/{recipient_id}/embed-session

Create Embed Session

Start an embedded signing session for one recipient. Returns a ceremony URL for your iframe or WebView that works once, for ten minutes. Opening it issues that recipient's signing link (any earlier link stops working, as with the signing-link mint) and shows the ceremony in place. How you hear `ready`, `completed`, `rejected` and `error` is `event_delivery`: postMessage to your page (framed) or to the ceremony's own window (top-level, for an injected script), or a `signenvoy-message://` navigation your WebView intercepts. A framed page's origin must be on the workspace's embed origins list (Settings → Workspace) or the browser refuses to frame the ceremony. Mint a fresh session on every render. 409 `invalid-state` unless the document is in flight and the recipient has not signed or declined; 404 for a recipient outside the document. A `message` session from a workspace with **no** embed origins can be shown by no page of yours: with a live-mode key it is refused, 409 `embed-origins-missing` (nothing is minted); with a test-mode key it is minted and the 201 carries `warnings` (and a `Warning` header) saying so, so you learn on the first call rather than from a blank frame. `redirect` and `none` sessions (a WebView, loaded top-level) need no origin and are never refused or warned.

Path

• doc_id string
• recipient_id string (uuid)

Request body (application/json)

Type: EmbedSessionReq | null

Responses

• 201 EmbedSessionOut (application/json): The session; `warnings` when a test-mode mint cannot be shown as asked
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): /problems/invalid-state unless the document is in flight and the recipient has not acted; /problems/embed-origins-missing for a live-mode key when event_delivery is message and the workspace has no embed origins (a test-mode key gets a 201 with `warnings`).
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/documents/{doc_id}/recipients/{recipient_id}/signing-link

Mint Signing Link

D86(e): a fresh signing link for one recipient. This ROTATES the recipient's link: the previous one (emailed, or returned earlier) stops working. No mail is sent. 409 `invalid-state` unless the document is in flight and the recipient has not signed or declined.

Path

• doc_id string
• recipient_id string (uuid)

Responses

• 201 MintedLinkOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/documents/{doc_id}/send

Send Document

Path

• doc_id string

Request body (application/json)

Type: SendReq | null

Responses

• 202 SendOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.

POST /v1/documents/{doc_id}/void

Void Document

Path

• doc_id string

Request body (application/json, required)

Responses

• 202 VoidOut (application/json): Successful Response
• 401 ProblemDetails (application/problem+json): /problems/unauthenticated
• 402 ProblemDetails (application/problem+json): /problems/live-mode-unavailable
• 403 ProblemDetails (application/problem+json): Workspace entitlement or access denied.
• 404 ProblemDetails (application/problem+json): Resource not found or not accessible to this key.
• 409 ProblemDetails (application/problem+json): Invalid state, conflict, or idempotency key conflict.
• 422 ProblemDetails (application/problem+json): Request schema or semantic validation failed; inspect type and detail.
• 429 ProblemDetails (application/problem+json): /problems/rate-limited; retry after Retry-After seconds.
• 500 ProblemDetails (application/problem+json): /problems/engine-error
• default ProblemDetails (application/problem+json): API error; type identifies the stable problem.

Problem types and recovery steps: error reference.