// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
{
"title": "Dummy Agreement",
"message": "Please review the privacy policy at your convenience and provide your signature.",
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"places" : [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "visitor"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "visitor",
"name": "John Doe",
"email": "john@example.com"
}
]
}
{
"id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Dummy Agreement",
"label": "Dummy Agreement for Order Ref. 25005",
"message": "Please review the agreement at your convenience and provide your electronic signature.",
"topics": [
"sales",
"project_blue"
],
"metadata": {
"customer_ref": "x9550501",
"account_annual_revenue": "$4,500,000"
},
"status": "processing",
"mode": "live",
"routing": "sequential",
"language": "en",
"timezone": "UTC",
"timestamp_format": "DD/MM/YYYY HH:mm:ss",
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe",
"accent_color": "#9810fa",
"email": {
"footer": "**Disclaimer:** This email and its attachments may contain confidential information. If you are not the intended recipient, please delete it and notify the sender.",
"logo_position": "left"
}
},
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Dummy Agreement",
"page_count": 2,
"url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx",
"format": "docx",
"data": {
"date": "December 31st, 2025",
"showAlert": true,
"serviceProvider": {
"name": "Jane Smith",
"organization": "ACME Global, Inc."
},
"client": {
"name": "Michael J. Miller",
"organization": "Miller Industries"
}
},
"places" : [
{
"key": "provider_signs_here",
"type": "signature",
"recipient_key": "service_provider",
"height": 60
},
{
"key": "client_signs_here",
"type": "signature",
"recipient_key": "client",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_26w2VVV5JVm4j459TY5BNM",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link"
}
],
"embeddable_in": [],
"redirect_url": null,
"url": null,
"url_variant": "standard"
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link"
}
],
"embeddable_in": [],
"redirect_url": null,
"url": null,
"url_variant": "standard"
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": {
"id": "del_1T7If8GgrTOf7zBVPaJf2e",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"status": "processing",
"type": "standard",
"language": "en",
"timezone": "UTC",
"timestamp_format": "DD/MM/YYYY hh:mm:ss",
"url": null,
"password": null,
"created_at": "2025-12-31T12:00:00.000Z",
"generated_at": null
},
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
Create a new envelope with documents and recipients to start the signing process
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
{
"title": "Dummy Agreement",
"message": "Please review the privacy policy at your convenience and provide your signature.",
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"places" : [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "visitor"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "visitor",
"name": "John Doe",
"email": "john@example.com"
}
]
}
{
"id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Dummy Agreement",
"label": "Dummy Agreement for Order Ref. 25005",
"message": "Please review the agreement at your convenience and provide your electronic signature.",
"topics": [
"sales",
"project_blue"
],
"metadata": {
"customer_ref": "x9550501",
"account_annual_revenue": "$4,500,000"
},
"status": "processing",
"mode": "live",
"routing": "sequential",
"language": "en",
"timezone": "UTC",
"timestamp_format": "DD/MM/YYYY HH:mm:ss",
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe",
"accent_color": "#9810fa",
"email": {
"footer": "**Disclaimer:** This email and its attachments may contain confidential information. If you are not the intended recipient, please delete it and notify the sender.",
"logo_position": "left"
}
},
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Dummy Agreement",
"page_count": 2,
"url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx",
"format": "docx",
"data": {
"date": "December 31st, 2025",
"showAlert": true,
"serviceProvider": {
"name": "Jane Smith",
"organization": "ACME Global, Inc."
},
"client": {
"name": "Michael J. Miller",
"organization": "Miller Industries"
}
},
"places" : [
{
"key": "provider_signs_here",
"type": "signature",
"recipient_key": "service_provider",
"height": 60
},
{
"key": "client_signs_here",
"type": "signature",
"recipient_key": "client",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_26w2VVV5JVm4j459TY5BNM",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link"
}
],
"embeddable_in": [],
"redirect_url": null,
"url": null,
"url_variant": "standard"
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link"
}
],
"embeddable_in": [],
"redirect_url": null,
"url": null,
"url_variant": "standard"
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": {
"id": "del_1T7If8GgrTOf7zBVPaJf2e",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"status": "processing",
"type": "standard",
"language": "en",
"timezone": "UTC",
"timestamp_format": "DD/MM/YYYY hh:mm:ss",
"url": null,
"password": null,
"created_at": "2025-12-31T12:00:00.000Z",
"generated_at": null
},
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
label property to add an internal description that won’t be shown to recipients.Show PDF Document
null.pdf and docx.For PDF documents the format must be pdf.Show fixed position
place.key values defined in the document’s places list.Show signature place
recipient_key, needs to sign.signature.recipient.key values in the envelope’s recipient list.Show initials place
recipient_key, needs to write their initials.initials.recipient.key values in the envelope’s recipient list.Show text place
text.#000000 (black).Show text input place
text_input.recipient.key values in the envelope’s recipient list.captures object of the Envelope.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.required or optional. The default is required.emailzipcode-us/, for example: /^[a-z0-9]{1,10}$/Show checkbox place
checkbox.recipient.key values in the envelope’s recipient list.captures object of the Envelope.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.check and xmark. The default is check.required or optional. The default is optional.Show dropdown place
dropdown.recipient.key values in the envelope’s recipient list.label (displayed to the user) and an optional value (captured when selected). If value is omitted, the label is used as the value."options": [
{ "label": "Option A", "value": "a" },
{ "label": "Option B", "value": "b" }
]
| Value | Description |
|---|---|
world_countries_names | Country names (e.g., “United States”, “Canada”) |
world_countries_2_letter_codes | ISO 3166-1 alpha-2 codes (e.g., “US”, “CA”) |
world_countries_3_letter_codes | ISO 3166-1 alpha-3 codes (e.g., “USA”, “CAN”) |
world_countries_numeric_codes | ISO 3166-1 numeric codes (e.g., “840”, “124”) |
us_states_names | US state names (e.g., “California”, “Texas”) |
us_states_2_letter_codes | US state codes (e.g., “CA”, “TX”) |
label of each option. If no match is found, it is matched against the value of each option. If no match is found, a validation error is returned.auto (default): Automatically selects the best behavior based on the number of options. Uses select for 10 or fewer options, and combobox for more than 10 options.select: Displays a standard dropdown list. Best for short lists where users can quickly scan all options.combobox: Displays a searchable dropdown with type-ahead filtering. Best for long lists where users need to search for their selection.required or optional. The default is required.captures object of the Envelope.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.Show recipient completed date place
recipient_key, completed (for example, signed) the envelope.recipient_completed_date.recipient.key values in the envelope’s recipient list.D MMM YYYY, which outputs as 31 Dec 2025.Show envelope completed date place
envelope_completed_date.D MMM YYYY, which outputs as 31 Dec 2025.Show DOCX Document
null.pdf and docx.For DOCX documents the format must be docx.Show fixed position
place.key values defined in the document’s places list.Show signature place
recipient_key, needs to sign.signature.recipient.key values in the envelope’s recipient list.Show initials place
recipient_key, needs to write their initials.initials.recipient.key values in the envelope’s recipient list.Show text place
text.#000000 (black).Show text input place
text_input.recipient.key values in the envelope’s recipient list.captures object of the Envelope.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.required or optional. The default is required.emailzipcode-us/, for example: /^[a-z0-9]{1,10}$/Show checkbox place
checkbox.recipient.key values in the envelope’s recipient list.captures object of the Envelope.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.check and xmark. The default is check.required or optional. The default is optional.Show dropdown place
dropdown.recipient.key values in the envelope’s recipient list.label (displayed to the user) and an optional value (captured when selected). If value is omitted, the label is used as the value."options": [
{ "label": "Option A", "value": "a" },
{ "label": "Option B", "value": "b" }
]
| Value | Description |
|---|---|
world_countries_names | Country names (e.g., “United States”, “Canada”) |
world_countries_2_letter_codes | ISO 3166-1 alpha-2 codes (e.g., “US”, “CA”) |
world_countries_3_letter_codes | ISO 3166-1 alpha-3 codes (e.g., “USA”, “CAN”) |
world_countries_numeric_codes | ISO 3166-1 numeric codes (e.g., “840”, “124”) |
us_states_names | US state names (e.g., “California”, “Texas”) |
us_states_2_letter_codes | US state codes (e.g., “CA”, “TX”) |
label of each option. If no match is found, it is matched against the value of each option. If no match is found, a validation error is returned.auto (default): Automatically selects the best behavior based on the number of options. Uses select for 10 or fewer options, and combobox for more than 10 options.select: Displays a standard dropdown list. Best for short lists where users can quickly scan all options.combobox: Displays a searchable dropdown with type-ahead filtering. Best for long lists where users need to search for their selection.required or optional. The default is required.captures object of the Envelope.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.Show recipient completed date place
recipient_key, completed (for example, signed) the envelope.recipient_completed_date.recipient.key values in the envelope’s recipient list.D MMM YYYY, which outputs as 31 Dec 2025.Show envelope completed date place
envelope_completed_date.D MMM YYYY, which outputs as 31 Dec 2025.Show Signer
signer, preparer, and approver.For signers, the type must be signer.email_link authentication will be created.Show Ceremony
Show Email Link Authentication
email_link, email_code, and custom.For link via email authentication, this type must be email_link.Show Email Code Authentication
email_link, email_code, and custom.For email code authentication, this type must be email_code.Show Custom Authentication
email_link, email_code, and custom.For custom authentication, this type must be custom.data must be sufficient for verifying the recipient’s authentication. For instance, an expert witness in a legal proceeding should be able to correlate these values with the authentication details in your system.When using custom authentication, you must retain all records necessary to prove the recipient’s authentication, such as session information. Please review our Terms & Conditions for more details.short and standard. The default is standard.Use short when you need to share the URL in space-constrained channels such as SMS or push notifications.https://app.example.com, but can also use wildcards, like https://*.example.com. For all available options, refer to the frame‑ancestors documentation.Defaults to an empty list ([]), meaning the ceremony cannot be embedded unless you explicitly allow at least one origin. To allow embedding in all origins (not recommended for production), use ["*"].email and none. The default is email.delivery_type to none, signed documents will not be automatically delivered to the recipient. You are responsible for distributing the signed documents through your own means and for complying with any applicable legal or contractual obligations regarding document delivery.typed and drawn. The default value for this property is ["typed", "drawn"].Show Deprecated Fields
automatic and manual. The default is automatic.recipient.ceremony object when creating an envelope.delivery_type to none and distribute it another way.If no deliverable is provided, a Standard Deliverable will be automatically generated.Show Standard Deliverable
standard and simple. The default is standard.standard: Includes all documents and an audit logsimple: Includes only the documents without an audit logstandard.********).Show Simple Deliverable
standard and simple. The default is standard.standard: Includes all documents and an audit logsimple: Includes only the documents without an audit logsimple.********).**text** to make text bold*text* to make text italic\n\n to create new paragraphsShow Branding
#2463eb).Defaults to #2463eb (blue) if not specified.Show Email Branding Options
**bold** for bold text*italic* for italic text\n\n for paragraph breaksleft, center, right. Default is left.sequential, where recipients sign one after another, or parallel, where all recipients can sign simultaneously. The default is sequential.Learn more about Recipient Routingen (English), es (Spanish), fr (French), it (Italian), pt (Portuguese), de (German), zh (Chinese), hu (Hungarian).If not specified, the account’s default language will be used.201 Created status code along with an envelope object after successful creation, or an error otherwise.
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
{
"title": "Dummy Agreement",
"message": "Please review the privacy policy at your convenience and provide your signature.",
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"places" : [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "visitor"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "visitor",
"name": "John Doe",
"email": "john@example.com"
}
]
}
{
"id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Dummy Agreement",
"label": "Dummy Agreement for Order Ref. 25005",
"message": "Please review the agreement at your convenience and provide your electronic signature.",
"topics": [
"sales",
"project_blue"
],
"metadata": {
"customer_ref": "x9550501",
"account_annual_revenue": "$4,500,000"
},
"status": "processing",
"mode": "live",
"routing": "sequential",
"language": "en",
"timezone": "UTC",
"timestamp_format": "DD/MM/YYYY HH:mm:ss",
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe",
"accent_color": "#9810fa",
"email": {
"footer": "**Disclaimer:** This email and its attachments may contain confidential information. If you are not the intended recipient, please delete it and notify the sender.",
"logo_position": "left"
}
},
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Dummy Agreement",
"page_count": 2,
"url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx",
"format": "docx",
"data": {
"date": "December 31st, 2025",
"showAlert": true,
"serviceProvider": {
"name": "Jane Smith",
"organization": "ACME Global, Inc."
},
"client": {
"name": "Michael J. Miller",
"organization": "Miller Industries"
}
},
"places" : [
{
"key": "provider_signs_here",
"type": "signature",
"recipient_key": "service_provider",
"height": 60
},
{
"key": "client_signs_here",
"type": "signature",
"recipient_key": "client",
"height": 60
}
]
}
],
"recipients": [
{
"id": "re_26w2VVV5JVm4j459TY5BNM",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link"
}
],
"embeddable_in": [],
"redirect_url": null,
"url": null,
"url_variant": "standard"
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "email_link"
}
],
"embeddable_in": [],
"redirect_url": null,
"url": null,
"url_variant": "standard"
},
"delivery_type": "email",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": {
"id": "del_1T7If8GgrTOf7zBVPaJf2e",
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"status": "processing",
"type": "standard",
"language": "en",
"timezone": "UTC",
"timestamp_format": "DD/MM/YYYY hh:mm:ss",
"url": null,
"password": null,
"created_at": "2025-12-31T12:00:00.000Z",
"generated_at": null
},
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
Was this page helpful?