Envelopes
Create an envelope
Create a new envelope with documents and recipients to start the signing process
Creates an envelope and starts the signing process. The envelope begins in processing status while documents are validated and recipients are queued for notification. It transitions to in_progress once recipients are notified.
At minimum, provide a title, at least one document, and at least one recipient. All other properties are optional.
Body parameters
Required
The title of the envelope, displayed to recipients in emails and the signing ceremony. Must be between 1 and 500 characters.
For an internal label that is not shown to recipients, use the label property instead.
The documents included in the envelope. An envelope can contain between 1 and 10 documents. Each document must be a publicly accessible PDF or DOCX file. Documents can include interactive places such as signature fields, text inputs, and checkboxes that recipients interact with during the signing ceremony. DOCX documents also support dynamic content via template data.
The recipients who participate in the envelope’s signing process. An envelope can have between 1 and 10 recipients.
Five types are supported:
signer: Signs the documents.preparer: Fills in fields before signers receive the documents.approver: Reviews and approves the documents without signing.automatic_signer: Has their signature applied automatically.qualified_signer: Signs with a qualified electronic signature (QES) through your own trust service provider. In public beta.
Signing options
Controls the order in which recipients receive and act on the envelope.
sequential: Recipients act one at a time, in the order listed. Each recipient must complete before the next is notified. This is the default.parallel: All recipients are notified at the same time and can act in any order.
Learn more about recipient routing.
Configuration for the deliverable generated when the envelope is completed. The deliverable is sent to all recipients via email. To prevent automatic delivery to a recipient, set that recipient’s delivery_type to none.
If omitted, a standard deliverable is generated automatically.
The regulatory attestation applied to the envelope. Use this to meet country-specific e-signature requirements.
none: No attestation. This is the default and covers most countries, including the US and EU member states.mx_nom151: Mexico NOM-151 compliance. Attaches a preservation certificate to the deliverable.br_icp_brasil: Brazil ICP-Brasil trusted timestamp. Embeds a timestamp in the deliverable.
For more information, see Attestation.
Recipient experience
A custom message included in the signing request emails sent to recipients. Use it to provide context about what is being signed.
Supports up to 2,000 characters. Accepts a subset of Markdown:
**bold**for bold text*italic*for italic text\n\nfor paragraph breaks
Defaults to null.
The language used for the signing ceremony, recipient emails, and the audit log in deliverables.
Supported values: en (English), es (Spanish), fr (French), it (Italian), pt (Portuguese), de (German), zh (Chinese Simplified), hu (Hungarian), nl (Dutch).
If not specified, the account’s default language is used.
Learn more about language.
The time zone applied to timestamps in the deliverable’s audit log. Must be a valid IANA Time Zone Database identifier (for example, America/New_York or Europe/London).
If not specified, the account’s default time zone is used.
Learn more about time zones.
The date and time format used for timestamps in the deliverable’s audit log. Uses MomentJS format tokens (for example, MM/DD/YYYY HH:mm:ss).
If not specified, the account’s default timestamp format is used.
Learn more about timestamp formats.
The sender of the envelope. Sender information appears in emails sent to recipients, identifying who initiated the signing request. If omitted, the account’s default sender name and email are used.
Customizes the visual appearance of the signing ceremony and recipient emails. Branding does not affect internal notifications or signed documents.
Learn more about branding.
Organization
A custom label for internal identification. Labels are not shown to recipients. Unlike title, which recipients see, the label is for your team’s use only. It can be updated at any time via the Update Envelope endpoint.
Maximum 500 characters. Defaults to null.
An array of up to 10 tags used to classify the envelope and filter webhook notifications. Each topic must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters per topic.
Learn more about topics.
A set of up to 10 custom key-value pairs for attaching internal reference data to the envelope. Use metadata to link envelopes to records in your own systems.
Keys: up to 32 characters (letters, digits, and underscores). Values: up to 1,000 characters. Do not store sensitive information as metadata.
Learn more about metadata.
Returns
Returns a 201 Created status code along with an envelope object on success, or an error otherwise.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement",
"message": "Please review the agreement and provide your signature.",
"routing": "parallel",
"documents": [
{
"key": "service_agreement",
"title": "Service Agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
"format": "pdf",
"places": [
{
"key": "client_signs_here",
"type": "signature",
"recipient_key": "client"
},
{
"key": "provider_signs_here",
"type": "signature",
"recipient_key": "provider"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "client",
"name": "Jane Doe",
"email": "jane.doe@example.com"
},
{
"type": "signer",
"key": "provider",
"name": "John Smith",
"email": "john.smith@example.com"
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Service Agreement",
"message": "Please review the agreement and provide your signature.",
"routing": "parallel",
"documents": [
{
"key": "service_agreement",
"title": "Service Agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
"format": "pdf",
"places": [
{
"key": "client_signs_here",
"type": "signature",
"recipient_key": "client"
},
{
"key": "provider_signs_here",
"type": "signature",
"recipient_key": "provider"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "client",
"name": "Jane Doe",
"email": "jane.doe@example.com"
},
{
"type": "signer",
"key": "provider",
"name": "John Smith",
"email": "john.smith@example.com"
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Service Agreement",
"message": "Please review the agreement and provide your signature.",
"routing": "parallel",
"documents": [
{
"key": "service_agreement",
"title": "Service Agreement",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
"format": "pdf",
"places": [
{
"key": "client_signs_here",
"type": "signature",
"recipient_key": "client"
},
{
"key": "provider_signs_here",
"type": "signature",
"recipient_key": "provider"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "client",
"name": "Jane Doe",
"email": "jane.doe@example.com"
},
{
"type": "signer",
"key": "provider",
"name": "John Smith",
"email": "john.smith@example.com"
}
]
}
}POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Offer Letter",
"label": "Offer Letter for Maria Garcia",
"routing": "sequential",
"message": "Welcome to Acme Corp! Please review and sign your offer letter.",
"topics": [
"hr",
"onboarding"
],
"metadata": {
"candidate_ref": "hr-2210"
},
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_42NTdNnkg6dGLx8jR1X1wm",
"accent_color": "#9810fa",
"email": {
"footer": "**Confidential:** this email is intended only for the named recipient.",
"logo_position": "left"
}
},
"timezone": "America/New_York",
"documents": [
{
"key": "offer_letter",
"title": "Offer Letter",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-offer-letter-template.docx",
"format": "docx",
"data": {
"candidateName": "Maria Garcia",
"position": "Product Designer",
"startDate": "December 1, 2026",
"salary": "$92,000"
},
"places": [
{
"key": "candidate_signs_here",
"type": "signature",
"recipient_key": "candidate",
"height": 60
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "hiring_manager",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "candidate",
"name": "Maria Garcia",
"email": "maria.garcia@example.com",
"signature_options": [
"typed",
"drawn"
],
"delivery_type": "email",
"ceremony": {
"authentication": [
{
"type": "email_code"
}
],
"redirect_url": "https://acme.example/welcome",
"embeddable_in": [],
"url_variant": "standard"
}
}
],
"deliverable": {
"type": "standard",
"language": "en",
"timezone": "America/New_York",
"timestamp_format": "MM/DD/YYYY HH:mm:ss"
}
}npx signatureapi envelopes create --body - <<'EOF'
{
"title": "Offer Letter",
"label": "Offer Letter for Maria Garcia",
"routing": "sequential",
"message": "Welcome to Acme Corp! Please review and sign your offer letter.",
"topics": [
"hr",
"onboarding"
],
"metadata": {
"candidate_ref": "hr-2210"
},
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_42NTdNnkg6dGLx8jR1X1wm",
"accent_color": "#9810fa",
"email": {
"footer": "**Confidential:** this email is intended only for the named recipient.",
"logo_position": "left"
}
},
"timezone": "America/New_York",
"documents": [
{
"key": "offer_letter",
"title": "Offer Letter",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-offer-letter-template.docx",
"format": "docx",
"data": {
"candidateName": "Maria Garcia",
"position": "Product Designer",
"startDate": "December 1, 2026",
"salary": "$92,000"
},
"places": [
{
"key": "candidate_signs_here",
"type": "signature",
"recipient_key": "candidate",
"height": 60
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "hiring_manager",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "candidate",
"name": "Maria Garcia",
"email": "maria.garcia@example.com",
"signature_options": [
"typed",
"drawn"
],
"delivery_type": "email",
"ceremony": {
"authentication": [
{
"type": "email_code"
}
],
"redirect_url": "https://acme.example/welcome",
"embeddable_in": [],
"url_variant": "standard"
}
}
],
"deliverable": {
"type": "standard",
"language": "en",
"timezone": "America/New_York",
"timestamp_format": "MM/DD/YYYY HH:mm:ss"
}
}
EOF{
"name": "create_envelope",
"arguments": {
"title": "Offer Letter",
"label": "Offer Letter for Maria Garcia",
"routing": "sequential",
"message": "Welcome to Acme Corp! Please review and sign your offer letter.",
"topics": [
"hr",
"onboarding"
],
"metadata": {
"candidate_ref": "hr-2210"
},
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_42NTdNnkg6dGLx8jR1X1wm",
"accent_color": "#9810fa",
"email": {
"footer": "**Confidential:** this email is intended only for the named recipient.",
"logo_position": "left"
}
},
"timezone": "America/New_York",
"documents": [
{
"key": "offer_letter",
"title": "Offer Letter",
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-offer-letter-template.docx",
"format": "docx",
"data": {
"candidateName": "Maria Garcia",
"position": "Product Designer",
"startDate": "December 1, 2026",
"salary": "$92,000"
},
"places": [
{
"key": "candidate_signs_here",
"type": "signature",
"recipient_key": "candidate",
"height": 60
}
]
}
],
"recipients": [
{
"type": "approver",
"key": "hiring_manager",
"name": "Alex Chen",
"email": "alex.chen@example.com"
},
{
"type": "signer",
"key": "candidate",
"name": "Maria Garcia",
"email": "maria.garcia@example.com",
"signature_options": [
"typed",
"drawn"
],
"delivery_type": "email",
"ceremony": {
"authentication": [
{
"type": "email_code"
}
],
"redirect_url": "https://acme.example/welcome",
"embeddable_in": [],
"url_variant": "standard"
}
}
],
"deliverable": {
"type": "standard",
"language": "en",
"timezone": "America/New_York",
"timestamp_format": "MM/DD/YYYY HH:mm:ss"
}
}
}{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Service Agreement",
"label": null,
"message": "Please review the agreement and provide your signature.",
"status": "processing",
"mode": "test",
"routing": "parallel",
"language": "en",
"timezone": "UTC",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"attestation": "none",
"branding": {
"logo": null,
"accent_color": "#2463eb",
"email": {
"from": "noreply@signatureapi.com",
"footer": null,
"logo_position": "left"
}
},
"sender": {
"name": "Acme Corp Legal",
"email": "legal@acme.example",
"organization": "Acme Corp"
},
"topics": [],
"metadata": {},
"documents": [
{
"id": "doc_4YvlxUZN28CeonDq6rTbvk",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"key": "service_agreement",
"title": "Service Agreement",
"page_count": 1,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
"format": "pdf",
"fixed_positions": [],
"places": [
{
"key": "client_signs_here",
"type": "signature",
"recipient_key": "client",
"height": 60
},
{
"key": "provider_signs_here",
"type": "signature",
"recipient_key": "provider",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_49r1R2jpPDz8hSpP75ZkPp",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "client",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link",
"subject_override": null,
"message_override": null
}
],
"redirect_url": null,
"redirect_delay": 3,
"embeddable_in": [],
"url_variant": "standard",
"url": null
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": [
"typed",
"drawn"
],
"completed_at": null,
"status_updated_at": "2026-11-02T14:03:11.000Z"
},
{
"id": "re_4VP9v4uPj6jwZzQ14CG2O8",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "provider",
"name": "John Smith",
"email": "john.smith@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link",
"subject_override": null,
"message_override": null
}
],
"redirect_url": null,
"redirect_delay": 3,
"embeddable_in": [],
"url_variant": "standard",
"url": null
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": [
"typed",
"drawn"
],
"completed_at": null,
"status_updated_at": "2026-11-02T14:03:11.000Z"
}
],
"deliverable": {
"id": "del_6FF89lKNyTNamOJCJd1tLL",
"name": null,
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "standard",
"status": "pending",
"url": null,
"language": "en",
"timezone": "UTC",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"included_documents": [
"service_agreement"
],
"password": null,
"created_at": "2026-11-02T14:03:11.000Z",
"generated_at": null
},
"captures": {},
"snapshot_url": null,
"created_at": "2026-11-02T14:03:11.000Z",
"completed_at": null
}{
"type": "https://signatureapi.com/docs/v1/errors/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The request body contains validation errors.",
"errors": [
"recipients[0].email must be a valid email address"
]
}{
"id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
"title": "Offer Letter",
"label": "Offer Letter for Maria Garcia",
"message": "Welcome to Acme Corp! Please review and sign your offer letter.",
"status": "processing",
"mode": "test",
"routing": "sequential",
"language": "en",
"timezone": "America/New_York",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"attestation": "none",
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_42NTdNnkg6dGLx8jR1X1wm",
"accent_color": "#9810fa",
"email": {
"from": "noreply@signatureapi.com",
"footer": "**Confidential:** this email is intended only for the named recipient.",
"logo_position": "left"
}
},
"sender": {
"name": "Acme Corp Legal",
"email": "legal@acme.example",
"organization": "Acme Corp"
},
"topics": [
"hr",
"onboarding"
],
"metadata": {
"candidate_ref": "hr-2210"
},
"documents": [
{
"id": "doc_0Pwd2LsJXeWGOJQwRctqC1",
"envelope_id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
"key": "offer_letter",
"title": "Offer Letter",
"page_count": 1,
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-offer-letter-template.docx",
"format": "docx",
"data": {
"candidateName": "Maria Garcia",
"position": "Product Designer",
"startDate": "December 1, 2026",
"salary": "$92,000"
},
"fixed_positions": [],
"places": [
{
"key": "candidate_signs_here",
"type": "signature",
"recipient_key": "candidate",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_1mdt9PluVuu4QIhYYe8R1P",
"envelope_id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
"type": "approver",
"key": "hiring_manager",
"name": "Alex Chen",
"email": "alex.chen@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link",
"subject_override": null,
"message_override": null
}
],
"redirect_url": null,
"redirect_delay": 3,
"embeddable_in": [],
"url_variant": "standard",
"url": null
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"completed_at": null,
"status_updated_at": "2026-11-02T16:30:00.000Z"
},
{
"id": "re_2f0wBwlt2te0kjU5QeL3Nl",
"envelope_id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
"type": "signer",
"key": "candidate",
"name": "Maria Garcia",
"email": "maria.garcia@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_code"
}
],
"redirect_url": "https://acme.example/welcome",
"redirect_delay": 3,
"embeddable_in": [],
"url_variant": "standard",
"url": null
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": [
"typed",
"drawn"
],
"completed_at": null,
"status_updated_at": "2026-11-02T16:30:00.000Z"
}
],
"deliverable": {
"id": "del_4l3fQxvjRTltbPbzIbOlmK",
"name": null,
"envelope_id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
"type": "standard",
"status": "pending",
"url": null,
"language": "en",
"timezone": "America/New_York",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"included_documents": [
"offer_letter"
],
"password": null,
"created_at": "2026-11-02T16:30:00.000Z",
"generated_at": null
},
"captures": {},
"snapshot_url": null,
"created_at": "2026-11-02T16:30:00.000Z",
"completed_at": null
}Errors every call can return are in Errors and Authentication.