Body Parameters
Core Parameters
These are the essential parameters required to define and send an envelope.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.A collection of documents to be signed.
Show PDF Document
Show PDF Document
The title of the document. It may be shown to recipients.
The URL where the document or template is located. Must be a publicly accessible URL.You can also use the URL returned by the Create Upload endpoint.Learn more about options in Document URL and Upload.
The format of the document or template. Available options are
pdf and docx.For PDF documents the format must be pdf.Show fixed position
Show fixed position
A user-provided key that identifies a place within a document.It must match one of the
place.key values defined in the document’s places 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 one of the
recipient.key values in the envelope’s recipient list.The height of the signature place in . The width is calculated based on a 5:2 ratio.Must be between 20 and 60. The default is 60.
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 one of the
recipient.key values in the envelope’s recipient list.The height of the initials place in . The width is the same as the height.Must be between 20 and 60. The default is 60.
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.Must be between 1 and 144. The 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 one of the
recipient.key values 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.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.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:
emailzipcode-us- a custom regular expression, enclosed in
/, for example:/^[a-z0-9]{1,10}$/
The message displayed when the user’s input does not match the required format.Learn more in Format Validation -> Adding a Custom Message.
The initial width of the text input place in .Must be between 30 and 540. The default is 30.
The font size in .Must be between 6 and 12. The default is 12.
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 one of the
recipient.key values 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.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.The symbol to display in the checkbox when it is checked.Available options are
check and xmark. The default is check.Specifies whether the recipient must check this box to complete the signing ceremony.Possible values are
required or optional. The default is optional.The height of the checkbox in . The width is the same as the height.Must be between 8 and 40. The default is 20.
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 one of the
recipient.key values 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.Show DOCX Document
Show DOCX Document
The title of the document. It may be shown to recipients.
The URL where the document or template is located. Must be a publicly accessible URL.You can also use the URL returned by the Create Upload endpoint.Learn more about options in Document URL and Upload.
The format of the document or template. Available options are
pdf and docx.For DOCX documents the format must be docx.The data to fill the template with.Keys must start with a lowercase letter and contain up to 32 alphanumeric characters. Values can be strings or booleans. Nested objects are allowed, but their values must also be strings or booleans.
Show fixed position
Show fixed position
A user-provided key that identifies a place within a document.It must match one of the
place.key values defined in the document’s places 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 one of the
recipient.key values in the envelope’s recipient list.The height of the signature place in . The width is calculated based on a 5:2 ratio.Must be between 20 and 60. The default is 60.
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 one of the
recipient.key values in the envelope’s recipient list.The height of the initials place in . The width is the same as the height.Must be between 20 and 60. The default is 60.
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.Must be between 1 and 144. The 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 one of the
recipient.key values 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.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.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:
emailzipcode-us- a custom regular expression, enclosed in
/, for example:/^[a-z0-9]{1,10}$/
The message displayed when the user’s input does not match the required format.Learn more in Format Validation -> Adding a Custom Message.
The initial width of the text input place in .Must be between 30 and 540. The default is 30.
The font size in .Must be between 6 and 12. The default is 12.
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 one of the
recipient.key values 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.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.The symbol to display in the checkbox when it is checked.Available options are
check and xmark. The default is check.Specifies whether the recipient must check this box to complete the signing ceremony.Possible values are
required or optional. The default is optional.The height of the checkbox in . The width is the same as the height.Must be between 8 and 40. The default is 20.
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 one of the
recipient.key values 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 Signer
Show Signer
Specifies the type of recipient. The only available option is
signer (we will add more recipient types soon).For signers, the type must be signer.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, numbers, and underscores, and start with a letter.
The name of the recipient.
The email address of the recipient.
The first ceremony to create for the recipient.If no ceremony is provided, a ceremony with
email_link authentication will be created.Show Ceremony
Show Ceremony
Show Email Link Authentication
Show Email Link Authentication
With link via email authentication, the recipient receives an email with a link to initiate the ceremony, sent by SignatureAPI.
Specifies the type of authentication. The available options are
email_link, email_code, and custom.For link via email authentication, this type must be email_link.Show Email Code Authentication
Show Email Code Authentication
With email code authentication, the recipient receives an email from SignatureAPI containing a code. The recipient must enter this code to authenticate during the ceremony.
Specifies the type of authentication. The available options are
email_link, email_code, and custom.For email code authentication, this type must be email_code.Show Custom Authentication
Show Custom Authentication
With custom authentication, your application receives a URL to share with the recipient. You can send this URL via email or embed it in a web or mobile application, enabling the recipient to initiate the ceremony.
Specifies the type of authentication. The available options are
email_link, email_code, and custom.For custom authentication, this type must be custom.The name of the authentication provider, such as your company or application. This value will appear in the envelope’s audit logs.
A set of key-value pairs with metadata about the authentication, such as timestamps, session IDs, and correlation IDs. These values will be included in the audit log.
The values provided in
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.A URL to redirect the recipient to after a ceremony is finished.Learn more in Redirect URL.
The type of ceremony URL returned for sharing flexibility.Available options are
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.List of sources allowed to embed this ceremony (for web embedding).These sources will be used in the frame-ancestor directive of the ceremony’s HTTP Content Security Policy (CSP).Sources usually take the form of a scheme and host, like
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 ["*"].To ensure compatibility, only the origin (scheme and host) is considered; paths are ignored.
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"].Show Deprecated Fields
Show Deprecated Fields
How the ceremony is created for the recipient.Available options are
automatic and manual. The default is automatic.This property is soft-deprecated but will continue to be supported for backwards compatibility. The recommended way to control ceremony creation is to use the
recipient.ceremony object when creating an envelope.Configuration for the that will be automatically generated when the envelope is completed.This deliverable is automatically sent to all recipients via email. To prevent automatic delivery, set a recipient’s
delivery_method to none and distribute it another way.If no deliverable is provided, a Standard Deliverable will be automatically generated.Show Standard Deliverable
Show Standard Deliverable
The Standard Deliverable includes the signed documents along with an audit log. If you just need the signed documents, use the Simple Deliverable instead.
The type of the deliverable.Available options are
standard and simple. The default is standard.standard: Includes all documents and an audit logsimple: Includes only the documents without an audit log
standard.The language for the deliverable. This setting determines the language of system-generated text and additional documents, such as the audit log. It does not affect the language of the signed documents.Refer to the list of available languages. By default, the language is set to match the language specified in the envelope.
The time zone for the deliverable. This setting determines the time zone used in system-generated documents, such as the audit log. It does not affect the times shown inside the signed documents.Refer to the list of available time zones. By default, the time zone matches the time zone specified in the envelope.
The timestamp format for the deliverable. This setting determines the format of timestamps used in system-generated documents, such as the audit log. It does not affect the timestamps shown inside the signed documents.Refer to the list of available timestamp formats. By default, the timestamp format matches the timestamp format specified in the envelope.
The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file.Password requirements:
- Between 4 and 32 characters
- Letters and numbers only (no special characters or spaces)
********).Password protection is available upon request. Contact support to enable this feature.
Show Simple Deliverable
Show Simple Deliverable
The Simple Deliverable includes only the signed documents without an audit log. If you need an audit log, use the Standard Deliverable instead.
The type of the deliverable.Available options are
standard and simple. The default is standard.standard: Includes all documents and an audit logsimple: Includes only the documents without an audit log
simple.The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file.Password requirements:
- Between 4 and 32 characters
- Letters and numbers only (no special characters or spaces)
********).Password protection is available upon request. Contact support to enable this feature.
Envelope Customization
These parameters let you tailor the signing process to meet specific workflow or user requirements.A message to include in emails to recipients.The message supports up to 2,000 characters and accepts a subset of Markdown formatting:
- Bold text: Use
**text**to make text bold - Italic text: Use
*text*to make text italic - Paragraph breaks: Use
\n\nto create new paragraphs
The order in which recipients sign the envelope. It can be
sequential, where recipients sign one after another, or parallel, where all recipients can sign simultaneously. The default is sequential.Learn more about Recipient RoutingThe language for the signer interface and related emails.Refer to the list of available languages. If not specified, the account’s default language will be used.
The time zone for this envelope. If not specified, the account’s default time zone will be used.
The timestamp format for this envelope. If not specified, the account’s default format will be used.
Specifies an attestation for the envelope, as required by certain country regulations. In most cases—including the US and EU member states—no special attestation is needed. For more information, see Attestation.
Envelope Details
These parameters help annotate and organize the envelope.Custom label given to the envelope for easier identification. Labels are for
internal use and are not shown to recipients.
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.Keys must start with a letter and contain up to 32 lowercase letters, numbers, or underscores. Values can be up to 1000 characters long.
Returns
Returns a201 Created status code along with an envelope object after successful creation, or an error otherwise.
Copy
Ask AI
// 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"
}
]
}
Copy
Ask AI
{
"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": "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
}