Create a draft envelope
const url = 'https://api.sealpost.app/v1/envelopes';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"title":"example","message":"example","subject":"example","status":"draft","test_mode":true,"files":[{"file_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","url":"https://example.com","base64":"example","name":"example","kind":"example"}],"recipients":[{"name":"example","email":"hello@example.com","kind":"signer","routing_order":1,"required":true,"phone":"example","language":"example","redirect_url":"https://example.com"}],"fields":[{"identifier":"example","type":"signature","recipient":1,"file":0,"page":1,"x":1,"y":1,"width":1,"height":1,"unit":"pt","requirement":"required","label":"example","placeholder":"example","options":["example"],"group":"example"}],"flexible_signing":false,"sequential":false,"allow_decline":true,"allow_reassign":false,"requester_name":"example","requester_email":"hello@example.com","redirect_url":"https://example.com","redirect_decline_url":"https://example.com","expires_at":"2026-04-15T12:00:00Z","language":"en","metadata":{"additionalProperty":"example"},"client_reference":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.sealpost.app/v1/envelopes \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "title": "example", "message": "example", "subject": "example", "status": "draft", "test_mode": true, "files": [ { "file_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "url": "https://example.com", "base64": "example", "name": "example", "kind": "example" } ], "recipients": [ { "name": "example", "email": "hello@example.com", "kind": "signer", "routing_order": 1, "required": true, "phone": "example", "language": "example", "redirect_url": "https://example.com" } ], "fields": [ { "identifier": "example", "type": "signature", "recipient": 1, "file": 0, "page": 1, "x": 1, "y": 1, "width": 1, "height": 1, "unit": "pt", "requirement": "required", "label": "example", "placeholder": "example", "options": [ "example" ], "group": "example" } ], "flexible_signing": false, "sequential": false, "allow_decline": true, "allow_reassign": false, "requester_name": "example", "requester_email": "hello@example.com", "redirect_url": "https://example.com", "redirect_decline_url": "https://example.com", "expires_at": "2026-04-15T12:00:00Z", "language": "en", "metadata": { "additionalProperty": "example" }, "client_reference": "example" }'Scope envelopes:write. Files by file_id (from /files), url or base64, in order;
recipients; fields placed by page and box in a declared unit (pt default, px72,
px96, percent; see docs/envelopes.md). Every box is converted to points and checked
against the file’s real page size (invalid_field_geometry). test_mode is taken from
the key or Sign-Test-Mode, never from the body, and is immutable. A signer needs at least
one field unless flexible_signing is true. Created as draft; sending is a later
operation. Honours Idempotency-Key.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Client-chosen key, 1 to 255 characters, scoped to (tenant, API key,
method, path). The first response is stored for 24 hours and replayed
for repeats with the same body (Idempotent-Replayed: true). A repeat
with a different body is a 422 idempotency_key_reused; a repeat while
the first request is still running is a 409 idempotency_in_flight
(a request that dies mid-flight releases its lock after 60 seconds).
Request Bodyrequired
Section titled “Request Bodyrequired”object
Only draft in this release.
Optional and informational: must agree with the key / Sign-Test-Mode, which decide.
One of file_id (from /files), url, or base64 + name; plus an optional kind.
object
object
Only meaningful when the envelope is sequential.
E.164, for SMS authentication later.
A box on one page of one file, in the declared unit. The verbatim object is kept as source.
object
Unique within the envelope; defaults to {type}_{n}.
Index into recipients. Required except for note.
Index into files.
1-based page within that file.
Coordinate unit of a field box. pt PDF points (default); px72 pixels of a 72 dpi
render, which equal points and are what the EMA CRM’s field table uses; px96 pixels of
a 96 dpi render (CSS px, x 0.75); percent of the visual page width (x, width) and height
(y, height). Origin is the top-left of the page as a viewer shows it. See docs/envelopes.md.
Choices for radio and dropdown.
Radio / checkbox group key.
No fields; each signer places their own signature (the CRM’s fallback when a document type has no field map).
At least one hour in the future.
Your own key/value bag, returned unchanged and filterable later. Keys match ^[A-Za-z0-9_.-]{1,40}$.
object
Responses
Section titled “Responses”The envelope with its files, recipients and fields (fields in points).
object
object
object
Null until the file is attached to an envelope.
1-based order within the envelope.
The caller’s label for the document type, e.g. merchant_application; used to split a signed envelope back into its documents.
SHA-256 (hex) of the original bytes, exactly as uploaded. Null while pending.
One page’s visual size in points (after /Rotate).
object
When an unattached upload is swept (30 days). Null once attached.
object
Always returned in points (unit: pt), origin top-left; source is what you sent.
object
Example
{ "status": "draft", "files": [ { "page_sizes": [ { "rotate": 0 } ], "status": "pending" } ], "recipients": [ { "status": "pending" } ], "fields": [ { "unit": "pt" } ]}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
Present and true when the response was replayed from a stored earlier response for the same Idempotency-Key.
The request could not be read (malformed JSON, bad header).
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
No key, an unknown key, or a revoked or expired key.
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
The key is valid but lacks the scope, or a test key tried a live-only action.
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
A request with the same Idempotency-Key is still in flight.
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
A file is over 25 MB (10 MB inline as base64); use /files/presign.
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
The request was read but a value is invalid, or an Idempotency-Key was reused with a different body.
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
The key is over its per-minute budget (600 live, 60 test, sliding window).
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
Seconds to wait before retrying.
Requests allowed per minute for this key (600 live, 60 test).
Requests remaining in the current window.
Seconds until the window has capacity again.
Something failed on our side. The request_id is in our logs.
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
The document service could not be reached; nothing was stored. Retry after Retry-After seconds with the same Idempotency-Key.
RFC 9457 problem details plus a stable code and the request_id.
object
https://sealpost.app/errors/{code}
Human-readable, safe to show to a developer, never contains secrets or signer data.
The request path.
Stable machine-readable code from the catalogue (docs/errors.md).
Field-level detail on validation_failed.
object
JSON pointer-ish path, e.g. scopes[2].
Example
{ "type": "https://sealpost.app/errors/insufficient_scope", "title": "Forbidden", "status": 403, "detail": "This key lacks the api_keys:write scope.", "code": "insufficient_scope", "request_id": "req_01J9ZK3V8Q4M2XQ7W0E5D1R6TA"}Headers
Section titled “Headers”Unique id of this request (req_…). Quote it in support requests.
Seconds to wait before retrying.