Create an envelope
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
{
"title": "Dummy Agreement",
"label": "Dummy Agreement for Order Ref. 25005",
"routing": "sequential",
"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"
},
"documents": [
{
"title": "Dummy Agreement",
"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": [
{
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "jane@example.com",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"delivery_type": "email"
},
{
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"delivery_type": "email"
}
]
}
{
"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",
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"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": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
This operation creates an envelope and starts the signing process, sending the documents to the recipients.
Body Parameters
The title of the envelope, which is shown to recipients.
Additionally, you can use the label property to add an internal description that won’t be shown to recipients.
Custom label given to the envelope for easier identification. Labels are for internal use and are not shown to recipients.
A message to include in emails to recipients.
The order in which recipients sign the envelope. It can be parallel, where all recipients can sign simultaneously, or sequential, where recipients sign one after another. The default is parallel.
Learn more about Recipient Routing
The language for the signer interface and related emails.
Refer to the list of available languages. The default value is en (English).
The timestamp format for this envelope.
An array of up to 10 strings used to classify envelopes and filter webhook notifications.
Each topic can have up to 32 lowercase alphanumeric characters and underscores, and must start with a letter.
A set of up to 10 custom key-value pairs containing metadata about the envelope.
A collection of documents to be signed.
Show document
Show document
The title of the document. It may be shown to recipients.
The URL where the document or template is located. Learn more about providing files to SignatureAPI.
The format of the document or template.
Available options are pdf and docx. The default is pdf.
The data to fill the template with.
Object keys must be alphanumeric.
Show fixed position
Show fixed position
A user-provided key that identifies a place within a document.
It must match to one of the keys in the document’s place list.
The page number for this position.
The distance, in points (or 1/72th of an inch), from the top border of the page to the position.
The distance, in points (or 1/72th of an inch), from the left border of the page to the position.
Defined areas within a document where a recipient either provides input, such as a signature, or where a constant or calculated value is added, like a completion date.
Learn more about places.
Show signature place
Show signature place
A space where the recipient, identified by the recipient_key, needs to sign.
Specifies the type of place.
For a signature place, the value must be signature.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
The height of the place within the document in . The width is calculated based on a 5:2 ratio.
The default height is 60 points.
Show initials place
Show initials place
A space where the recipient, identified by the recipient_key, needs to write their initials.
Specifies the type of place.
For an initials place, the value must be initials.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
The height of the place within the document in . The width is the same as the height.
The default height is 60 points.
Show text place
Show text place
An arbitrary text string.
Specifies the type of place.
For a text place, the value must be text.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
The text content.
The font size in points. Default is 12.
The font color in hexadecimal notation. Default is #000000 (black).
Show text input place
Show text input place
A text input field to ask recipients to enter text.
Specifies the type of place.
For a text input place, the value must be text_input.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
A user-defined identifier used to store the value entered by the recipient. This value will be included in the captures object of the Envelope.
A tooltip message displayed over the input text field during the signing ceremony.
Learn more in Hints and Prompts.
A placeholder message shown inside the input text field during the signing ceremony.
Learn more in Hints and Prompts.
Specifies whether the recipient must fill this field to complete the signing ceremony.
Possible values are required or optional. The default is required.
Defines the validation format for the user’s input.
Accepted values are email or zipcode-us. Alternatively, a regular expression can be used, enclosed in forward slashes.
Learn more in Format Validation.
The message displayed when the user’s input does not match the required format.
Learn more in Format Validation -> Adding a Custom Message.
Show checkbox place
Show checkbox place
A checkbox field to ask recipients to check a box.
Specifies the type of place.
For a checkbox place, the value must be checkbox.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
A user-defined identifier used to store the value entered by the recipient. This value will be included in the captures object of the Envelope.
The symbol to display in the checkbox when it is checked.
Available options are check and xmark. The default is check.
Show recipient completed date place
Show recipient completed date place
The date when the recipient, identified by the recipient_key, completed (for example, signed) the envelope.
Specifies the type of place.
For this kind of place, the value must be recipient_completed_date.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
Defines the format of the date, using MomentJS date format definitions.
The default format is D MMM YYYY, which outputs as 31 Dec 2025.
Show envelope completed date place
Show envelope completed date place
The date when the envelope was completed.
Specifies the type of place.
For this kind of place, the value must be envelope_completed_date.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
Defines the format of the date, using MomentJS date format definitions.
The default format is D MMM YYYY, which outputs as 31 Dec 2025.
People that signs the documents in an envelope.
Show recipient
Show recipient
The type of the recipient.
Available options: signer (We will add more recipient types soon)
A unique identifier you assign to each recipient in the envelope.
It’s used to match recipients with the places they should interact with (like signature fields) and to identify them in events and webhook notifications.
It must be unique within the envelope, contain up to 32 lowercase letters or numbers, and start with a letter.
The name of the recipient.
The email address of the recipient.
How the ceremony is created for the recipient.
Available options are automatic and manual. The default is automatic.
How the deliverable (signed document) is delivered to the recipient.
Available options are email and none. The default is email.
To be able to set the delivery_type to none, please contact support.
An array that defines which signature types a recipient can use, with the first item shown as the default option during signing.
Available values for the array items are typed and drawn. The default value for this property is ["typed", "drawn"].
Returns
Returns a 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",
"label": "Dummy Agreement for Order Ref. 25005",
"routing": "sequential",
"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"
},
"documents": [
{
"title": "Dummy Agreement",
"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": [
{
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "jane@example.com",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"delivery_type": "email"
},
{
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"delivery_type": "email"
}
]
}
{
"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",
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"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": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
{
"title": "Dummy Agreement",
"label": "Dummy Agreement for Order Ref. 25005",
"routing": "sequential",
"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"
},
"documents": [
{
"title": "Dummy Agreement",
"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": [
{
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "jane@example.com",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"delivery_type": "email"
},
{
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"delivery_type": "email"
}
]
}
{
"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",
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"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": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
Create an envelope
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
{
"title": "Dummy Agreement",
"label": "Dummy Agreement for Order Ref. 25005",
"routing": "sequential",
"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"
},
"documents": [
{
"title": "Dummy Agreement",
"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": [
{
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "jane@example.com",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"delivery_type": "email"
},
{
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"delivery_type": "email"
}
]
}
{
"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",
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"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": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
This operation creates an envelope and starts the signing process, sending the documents to the recipients.
Body Parameters
The title of the envelope, which is shown to recipients.
Additionally, you can use the label property to add an internal description that won’t be shown to recipients.
Custom label given to the envelope for easier identification. Labels are for internal use and are not shown to recipients.
A message to include in emails to recipients.
The order in which recipients sign the envelope. It can be parallel, where all recipients can sign simultaneously, or sequential, where recipients sign one after another. The default is parallel.
Learn more about Recipient Routing
The language for the signer interface and related emails.
Refer to the list of available languages. The default value is en (English).
The timestamp format for this envelope.
An array of up to 10 strings used to classify envelopes and filter webhook notifications.
Each topic can have up to 32 lowercase alphanumeric characters and underscores, and must start with a letter.
A set of up to 10 custom key-value pairs containing metadata about the envelope.
A collection of documents to be signed.
Show document
Show document
The title of the document. It may be shown to recipients.
The URL where the document or template is located. Learn more about providing files to SignatureAPI.
The format of the document or template.
Available options are pdf and docx. The default is pdf.
The data to fill the template with.
Object keys must be alphanumeric.
Show fixed position
Show fixed position
A user-provided key that identifies a place within a document.
It must match to one of the keys in the document’s place list.
The page number for this position.
The distance, in points (or 1/72th of an inch), from the top border of the page to the position.
The distance, in points (or 1/72th of an inch), from the left border of the page to the position.
Defined areas within a document where a recipient either provides input, such as a signature, or where a constant or calculated value is added, like a completion date.
Learn more about places.
Show signature place
Show signature place
A space where the recipient, identified by the recipient_key, needs to sign.
Specifies the type of place.
For a signature place, the value must be signature.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
The height of the place within the document in . The width is calculated based on a 5:2 ratio.
The default height is 60 points.
Show initials place
Show initials place
A space where the recipient, identified by the recipient_key, needs to write their initials.
Specifies the type of place.
For an initials place, the value must be initials.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
The height of the place within the document in . The width is the same as the height.
The default height is 60 points.
Show text place
Show text place
An arbitrary text string.
Specifies the type of place.
For a text place, the value must be text.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
The text content.
The font size in points. Default is 12.
The font color in hexadecimal notation. Default is #000000 (black).
Show text input place
Show text input place
A text input field to ask recipients to enter text.
Specifies the type of place.
For a text input place, the value must be text_input.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
A user-defined identifier used to store the value entered by the recipient. This value will be included in the captures object of the Envelope.
A tooltip message displayed over the input text field during the signing ceremony.
Learn more in Hints and Prompts.
A placeholder message shown inside the input text field during the signing ceremony.
Learn more in Hints and Prompts.
Specifies whether the recipient must fill this field to complete the signing ceremony.
Possible values are required or optional. The default is required.
Defines the validation format for the user’s input.
Accepted values are email or zipcode-us. Alternatively, a regular expression can be used, enclosed in forward slashes.
Learn more in Format Validation.
The message displayed when the user’s input does not match the required format.
Learn more in Format Validation -> Adding a Custom Message.
Show checkbox place
Show checkbox place
A checkbox field to ask recipients to check a box.
Specifies the type of place.
For a checkbox place, the value must be checkbox.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
A user-defined identifier used to store the value entered by the recipient. This value will be included in the captures object of the Envelope.
The symbol to display in the checkbox when it is checked.
Available options are check and xmark. The default is check.
Show recipient completed date place
Show recipient completed date place
The date when the recipient, identified by the recipient_key, completed (for example, signed) the envelope.
Specifies the type of place.
For this kind of place, the value must be recipient_completed_date.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
A user-provided key that identifies a recipient within an envelope.
It must match to one of the keys in the envelope’s recipient list.
Defines the format of the date, using MomentJS date format definitions.
The default format is D MMM YYYY, which outputs as 31 Dec 2025.
Show envelope completed date place
Show envelope completed date place
The date when the envelope was completed.
Specifies the type of place.
For this kind of place, the value must be envelope_completed_date.
A user-provided key that identifies a place within a document.
It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
Defines the format of the date, using MomentJS date format definitions.
The default format is D MMM YYYY, which outputs as 31 Dec 2025.
People that signs the documents in an envelope.
Show recipient
Show recipient
The type of the recipient.
Available options: signer (We will add more recipient types soon)
A unique identifier you assign to each recipient in the envelope.
It’s used to match recipients with the places they should interact with (like signature fields) and to identify them in events and webhook notifications.
It must be unique within the envelope, contain up to 32 lowercase letters or numbers, and start with a letter.
The name of the recipient.
The email address of the recipient.
How the ceremony is created for the recipient.
Available options are automatic and manual. The default is automatic.
How the deliverable (signed document) is delivered to the recipient.
Available options are email and none. The default is email.
To be able to set the delivery_type to none, please contact support.
An array that defines which signature types a recipient can use, with the first item shown as the default option during signing.
Available values for the array items are typed and drawn. The default value for this property is ["typed", "drawn"].
Returns
Returns a 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",
"label": "Dummy Agreement for Order Ref. 25005",
"routing": "sequential",
"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"
},
"documents": [
{
"title": "Dummy Agreement",
"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": [
{
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "jane@example.com",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"delivery_type": "email"
},
{
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"delivery_type": "email"
}
]
}
{
"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",
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"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": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
{
"title": "Dummy Agreement",
"label": "Dummy Agreement for Order Ref. 25005",
"routing": "sequential",
"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"
},
"documents": [
{
"title": "Dummy Agreement",
"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": [
{
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "jane@example.com",
"ceremony_creation": "automatic",
"signature_options": ["typed", "drawn"],
"delivery_type": "email"
},
{
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"ceremony_creation": "automatic",
"signature_options": ["drawn"],
"delivery_type": "email"
}
]
}
{
"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",
"sender": {
"name": "Jennifer Lee",
"email": "jennifer@example.com",
"organization": "Acme Enterprises"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"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": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "service_provider",
"name": "Jane Smith",
"email": "emily@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["typed", "drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "client",
"name": "Michael J. Miller",
"email": "michael@example.com",
"status": "pending",
"ceremony_creation": "automatic",
"delivery_type": "email",
"signature_options": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}