Introduction
Envelopes
Recipients
Deliverables
Copy
Ask AI
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json
{
"title": "Service Agreement",
"message": "Please review the privacy policy 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
// HTTP Status Code 201
{
"id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Exploration Agreement",
"label": "Exploration Agreement for Order Ref. 25005",
"message": "Please review the agreement and provide your 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": "MM/DD/YYYY HH:mm:ss",
"attestation": "none",
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe",
"accent_color": "#9810fa",
"email": {
"from": "noreply@signatureapi.com",
"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": "Exploration 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": "jane@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": "2025-12-31T12:00:01.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",
"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": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T12:00:01.000Z"
}
],
"deliverable": {
"id": "del_1T7If8GgrTOf7zBVPaJf2e",
"name": null,
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "standard",
"status": "pending",
"url": null,
"language": "en",
"timezone": "UTC",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"included_documents": null,
"password": null,
"created_at": "2025-12-31T12:00:00.000Z",
"generated_at": null
},
"captures": {},
"snapshot_url": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
Envelopes
Create an envelope
Create a new envelope with documents and recipients to start the signing process
POST
/
v1
/
envelopes
Copy
Ask AI
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json
{
"title": "Service Agreement",
"message": "Please review the privacy policy 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
// HTTP Status Code 201
{
"id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Exploration Agreement",
"label": "Exploration Agreement for Order Ref. 25005",
"message": "Please review the agreement and provide your 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": "MM/DD/YYYY HH:mm:ss",
"attestation": "none",
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe",
"accent_color": "#9810fa",
"email": {
"from": "noreply@signatureapi.com",
"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": "Exploration 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": "jane@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": "2025-12-31T12:00:01.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",
"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": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T12:00:01.000Z"
}
],
"deliverable": {
"id": "del_1T7If8GgrTOf7zBVPaJf2e",
"name": null,
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "standard",
"status": "pending",
"url": null,
"language": "en",
"timezone": "UTC",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"included_documents": null,
"password": null,
"created_at": "2025-12-31T12:00:00.000Z",
"generated_at": null
},
"captures": {},
"snapshot_url": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
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.
Show PDF Document
Show PDF Document
A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API.Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters.If not provided, a key is generated automatically.
An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to
null if not provided. Maximum 500 characters.The URL where the document or template file is located. The file must be publicly accessible.You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the Create Upload endpoint.Learn more about your options in Document URL and Upload.
The file format of the document. Determines which features are available.
pdf— Standard PDF file. Supports places via placeholders or fixed positions.docx— Microsoft Word file. Supports template fields for dynamic content in addition to places.
pdf.Show fixed position
Show fixed position
The key of the place to position. Must match one of the
key values in the document’s places array.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The page number where the place is positioned. Page numbering starts at 1.
The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example,
360 places the field 5 inches from the top edge.The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example,
72 places the field 1 inch from the left edge.Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date).Each place has a
type that determines its behavior. A place must be positioned using either a [[place_key]] placeholder in the document text or an entry in the fixed_positions array.Learn more about places.Show signature place
Show signature place
A location where the recipient, identified by
recipient_key, draws or types their signature. A single recipient can have multiple signature places across different pages of a document.Specifies the type of place.For a signature place, the value must be
signature.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The height of the signature place in . The width is calculated automatically using a 5:2 ratio based on this height.Must be between 20 and 60. Defaults to 60.
Show initials place
Show initials place
A location where the recipient, identified by
recipient_key, enters their initials. A single recipient can have multiple initials places across different pages of a document.Specifies the type of place.For an initials place, the value must be
initials.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The height of the initials place in . The width equals the height.Must be between 20 and 60. Defaults to 60.
Show text place
Show text place
A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins.
Specifies the type of place.For a text place, the value must be
text.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient.Maximum length is 1000 characters.
The font size in points.Must be between 1 and 144. The default is 12.
The font color for this text place. Must be a six-digit hex color code with a leading
#. Defaults to #000000 (black).Show text input place
Show text input place
A location where the recipient, identified by
recipient_key, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use capture_as to store the entered value in the envelope’s captures.Specifies the type of place.For a text input place, the value must be
text_input.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.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 field in . The field may expand beyond this width during typing.Must be between 30 and 540. Defaults to 30.
The font size in .Must be between 6 and 12. Defaults to 12.
Show boxed text input place
Show boxed text input place
A series of individual character boxes where the recipient, identified by
recipient_key, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use capture_as to store the entered value in the envelope’s captures.Specifies the type of place.For a boxed text input place, the value must be
boxed_text_input.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The number of individual character boxes to display.Must be between 1 and 100. Each box accepts a single character from the recipient.
A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.A tooltip message displayed over the boxed text input field during the signing ceremony.Learn more in Hints and Prompts.
A placeholder message shown inside the first box during the signing ceremony to guide the recipient.Learn more in Hints and Prompts.
Specifies whether the recipient must fill all boxes to complete the signing ceremony.Possible values are
required or optional. The default is required.The total width of the boxed input field in .Must be between 30 and 540. The default is 30.
The height of each individual box in .
The font size in .Must be between 6 and 12. The default is 12.
Show multiline text input place
Show multiline text input place
A location where the recipient, identified by
recipient_key, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use capture_as to store the entered value in the envelope’s captures.Specifies the type of place.For a multi-line text input place, the value must be
multiline_text_input.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.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.The width of the multi-line text input place in .Must be between 30 and 540. The default is 30.
The number of lines for the multi-line text input field.Must be between 1 and 100.
The line height in . Must be greater than or equal to
font_size.Must be between 6 and 72. The default is 12.The font size in .Must be between 6 and 12. The default is 12.
Show checkbox place
Show checkbox place
A location where the recipient, identified by
recipient_key, checks or unchecks a box. Use capture_as to store the checkbox value in the envelope’s captures.Specifies the type of place.For a checkbox place, the value must be
checkbox.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.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 equals the height.Must be between 8 and 40. Defaults to 20.
Show dropdown place
Show dropdown place
A location where the recipient, identified by
recipient_key, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use capture_as to store the selected value in the envelope’s captures.Specifies the type of place.For a dropdown place, the value must be
dropdown.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.Specifies the list of options available in the dropdown.You can provide either custom options or a predefined option set.Custom options: An array of objects, each with a Predefined options: A string specifying a built-in option set:
label (displayed to the user) and an optional value (captured when selected). If value is omitted, the label is used as the value.Copy
Ask AI
"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”) |
Specifies the option that is pre-selected when the dropdown is displayed.The value is first matched against the
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.Specifies the behavior of the dropdown during the signing ceremony.Possible values:
auto(default): Automatically selects the best behavior based on the number of options. Usesselectfor 10 or fewer options, andcomboboxfor 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.
Specifies whether the recipient must select an option to complete the signing ceremony.Possible values are
required or optional. The default is required.A placeholder message shown inside the dropdown field during the signing ceremony.Maximum length is 100 characters.Learn more in Hints and Prompts.
A tooltip message displayed when the user hovers over or focuses on the dropdown field during the signing ceremony.Maximum length is 100 characters.Learn more in Hints and Prompts.
A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.The font size in .Must be between 6 and 12. The default is 12.
The width of the dropdown field in .Must be between 30 and 540. The default is 30.
Show recipient completed date place
Show recipient completed date place
Displays the date and time when the recipient, identified by
recipient_key, completed their action on the envelope. Use date_format to control how the date is formatted.Specifies the type of place.For this kind of place, the value must be
recipient_completed_date.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The date and time format using Moment.js syntax. Common formats include
D MMM YYYY (31 Dec 2025), YYYY-MM-DD (2025-12-31), and MM/DD/YYYY (12/31/2025).Defaults to D MMM YYYY.The font size in . Must be between 1 and 144. Defaults to 12.
Show envelope completed date place
Show envelope completed date place
Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use
date_format to control how the date is formatted.Specifies the type of place.For this kind of place, the value must be
envelope_completed_date.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The date and time format using Moment.js syntax. Common formats include
D MMM YYYY (31 Dec 2025), YYYY-MM-DD (2025-12-31), and MM/DD/YYYY (12/31/2025).Defaults to D MMM YYYY.The font size in . Must be between 1 and 144. Defaults to 12.
Show recipient name place
Show recipient name place
Displays the name of the recipient, identified by
recipient_key, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient.Specifies the type of place.For this kind of place, the value must be
recipient_name.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The font size in . Must be between 1 and 144. Defaults to 12.
Show recipient email place
Show recipient email place
Displays the email address of the recipient, identified by
recipient_key, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient.Specifies the type of place.For this kind of place, the value must be
recipient_email.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The font size in . Must be between 1 and 144. Defaults to 12.
Show DOCX Document
Show DOCX Document
A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API.Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters.If not provided, a key is generated automatically.
An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to
null if not provided. Maximum 500 characters.The URL where the document or template file is located. The file must be publicly accessible.You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the Create Upload endpoint.Learn more about your options in Document URL and Upload.
The file format of the document. Determines which features are available.
pdf— Standard PDF file. Supports places via placeholders or fixed positions.docx— Microsoft Word file. Supports template fields for dynamic content in addition to places.
docx.Template data used to fill dynamic fields in a DOCX template. Each key corresponds to a
{{key}} placeholder in the template file.Keys must be alphanumeric and at most 32 characters. Values can be strings, booleans, or nested objects. Nested keys map to dot-notation placeholders (for example, a key person with nested key name fills {{person.name}}). Defaults to {}.Show fixed position
Show fixed position
The key of the place to position. Must match one of the
key values in the document’s places array.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The page number where the place is positioned. Page numbering starts at 1.
The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example,
360 places the field 5 inches from the top edge.The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example,
72 places the field 1 inch from the left edge.Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date).Each place has a
type that determines its behavior. A place must be positioned using either a [[place_key]] placeholder in the document text or an entry in the fixed_positions array.Learn more about places.Show signature place
Show signature place
A location where the recipient, identified by
recipient_key, draws or types their signature. A single recipient can have multiple signature places across different pages of a document.Specifies the type of place.For a signature place, the value must be
signature.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The height of the signature place in . The width is calculated automatically using a 5:2 ratio based on this height.Must be between 20 and 60. Defaults to 60.
Show initials place
Show initials place
A location where the recipient, identified by
recipient_key, enters their initials. A single recipient can have multiple initials places across different pages of a document.Specifies the type of place.For an initials place, the value must be
initials.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The height of the initials place in . The width equals the height.Must be between 20 and 60. Defaults to 60.
Show text place
Show text place
A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins.
Specifies the type of place.For a text place, the value must be
text.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient.Maximum length is 1000 characters.
The font size in points.Must be between 1 and 144. The default is 12.
The font color for this text place. Must be a six-digit hex color code with a leading
#. Defaults to #000000 (black).Show text input place
Show text input place
A location where the recipient, identified by
recipient_key, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use capture_as to store the entered value in the envelope’s captures.Specifies the type of place.For a text input place, the value must be
text_input.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.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 field in . The field may expand beyond this width during typing.Must be between 30 and 540. Defaults to 30.
The font size in .Must be between 6 and 12. Defaults to 12.
Show boxed text input place
Show boxed text input place
A series of individual character boxes where the recipient, identified by
recipient_key, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use capture_as to store the entered value in the envelope’s captures.Specifies the type of place.For a boxed text input place, the value must be
boxed_text_input.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The number of individual character boxes to display.Must be between 1 and 100. Each box accepts a single character from the recipient.
A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.A tooltip message displayed over the boxed text input field during the signing ceremony.Learn more in Hints and Prompts.
A placeholder message shown inside the first box during the signing ceremony to guide the recipient.Learn more in Hints and Prompts.
Specifies whether the recipient must fill all boxes to complete the signing ceremony.Possible values are
required or optional. The default is required.The total width of the boxed input field in .Must be between 30 and 540. The default is 30.
The height of each individual box in .
The font size in .Must be between 6 and 12. The default is 12.
Show multiline text input place
Show multiline text input place
A location where the recipient, identified by
recipient_key, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use capture_as to store the entered value in the envelope’s captures.Specifies the type of place.For a multi-line text input place, the value must be
multiline_text_input.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.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.The width of the multi-line text input place in .Must be between 30 and 540. The default is 30.
The number of lines for the multi-line text input field.Must be between 1 and 100.
The line height in . Must be greater than or equal to
font_size.Must be between 6 and 72. The default is 12.The font size in .Must be between 6 and 12. The default is 12.
Show checkbox place
Show checkbox place
A location where the recipient, identified by
recipient_key, checks or unchecks a box. Use capture_as to store the checkbox value in the envelope’s captures.Specifies the type of place.For a checkbox place, the value must be
checkbox.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.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 equals the height.Must be between 8 and 40. Defaults to 20.
Show dropdown place
Show dropdown place
A location where the recipient, identified by
recipient_key, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use capture_as to store the selected value in the envelope’s captures.Specifies the type of place.For a dropdown place, the value must be
dropdown.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.Specifies the list of options available in the dropdown.You can provide either custom options or a predefined option set.Custom options: An array of objects, each with a Predefined options: A string specifying a built-in option set:
label (displayed to the user) and an optional value (captured when selected). If value is omitted, the label is used as the value.Copy
Ask AI
"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”) |
Specifies the option that is pre-selected when the dropdown is displayed.The value is first matched against the
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.Specifies the behavior of the dropdown during the signing ceremony.Possible values:
auto(default): Automatically selects the best behavior based on the number of options. Usesselectfor 10 or fewer options, andcomboboxfor 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.
Specifies whether the recipient must select an option to complete the signing ceremony.Possible values are
required or optional. The default is required.A placeholder message shown inside the dropdown field during the signing ceremony.Maximum length is 100 characters.Learn more in Hints and Prompts.
A tooltip message displayed when the user hovers over or focuses on the dropdown field during the signing ceremony.Maximum length is 100 characters.Learn more in Hints and Prompts.
A key that stores the recipient’s input in the envelope’s
captures object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to null to disable capture.The font size in .Must be between 6 and 12. The default is 12.
The width of the dropdown field in .Must be between 30 and 540. The default is 30.
Show recipient completed date place
Show recipient completed date place
Displays the date and time when the recipient, identified by
recipient_key, completed their action on the envelope. Use date_format to control how the date is formatted.Specifies the type of place.For this kind of place, the value must be
recipient_completed_date.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The date and time format using Moment.js syntax. Common formats include
D MMM YYYY (31 Dec 2025), YYYY-MM-DD (2025-12-31), and MM/DD/YYYY (12/31/2025).Defaults to D MMM YYYY.The font size in . Must be between 1 and 144. Defaults to 12.
Show envelope completed date place
Show envelope completed date place
Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use
date_format to control how the date is formatted.Specifies the type of place.For this kind of place, the value must be
envelope_completed_date.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The date and time format using Moment.js syntax. Common formats include
D MMM YYYY (31 Dec 2025), YYYY-MM-DD (2025-12-31), and MM/DD/YYYY (12/31/2025).Defaults to D MMM YYYY.The font size in . Must be between 1 and 144. Defaults to 12.
Show recipient name place
Show recipient name place
Displays the name of the recipient, identified by
recipient_key, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient.Specifies the type of place.For this kind of place, the value must be
recipient_name.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The font size in . Must be between 1 and 144. Defaults to 12.
Show recipient email place
Show recipient email place
Displays the email address of the recipient, identified by
recipient_key, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient.Specifies the type of place.For this kind of place, the value must be
recipient_email.A unique identifier for this place within the document. Use this key to match the place to its position, either through a
[[place_key]] placeholder in the document or an entry in fixed_positions.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.The key of the recipient assigned to this place. Must match one of the
key values in the envelope’s recipients array.The font size in . Must be between 1 and 144. Defaults to 12.
The recipients who participate in the envelope’s signing process. An envelope can have between 1 and 10 recipients.Three types are supported:
signer— Signs the documents.preparer— Fills in fields before signers receive the documents.approver— Reviews and approves the documents without signing.
Show Signer
Show Signer
The type of the recipient. Determines what actions the recipient can perform during the ceremony.
For signers, the type must be
| Type | Description |
|---|---|
signer | Signs documents. Every envelope must have at least one signer. |
approver | Reviews and approves documents without signing. |
preparer | Fills in document fields on behalf of another party. |
signer.A unique identifier you assign to each recipient in the envelope.Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.
The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures.
The email address of the recipient. Used to send invitation emails when
delivery_type is email.Configuration for the first ceremony to create for the recipient.If not provided, a ceremony with
email_link authentication is created by default.Show Ceremony
Show Ceremony
Show Email Link Authentication
Show Email Link Authentication
With email link authentication, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session.
The type of authentication. Available values:
email_link, email_code, and custom.For email link authentication, set type to email_link.A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the envelope title.Maximum 500 characters.
A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the envelope message.Supports Markdown formatting:
**bold**, *italic*, and \n\n for paragraph breaks. Maximum 2000 characters.Show Email Code Authentication
Show Email Code Authentication
With email code authentication, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony.
The type of authentication. Available values:
email_link, email_code, and custom.For email code authentication, set type to email_code.Show Custom Authentication
Show Custom Authentication
With custom authentication, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access.
The type of authentication. Available values:
email_link, email_code, and custom.For custom authentication, set type to custom.The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.
Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log.
The values in
data must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient’s authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity.Review our Terms & Conditions for details.An HTTPS URL to redirect the recipient to after the ceremony finishes.Learn more in Redirect URL.
The delay in seconds before the ceremony redirects to
redirect_url (standalone ceremonies) or emits completion events (embedded ceremonies).Defaults to 3. Allowed range: 0 to 20.Learn more in Redirect URL.The format of the ceremony URL.Available options:
standard(default): Full-length URL. Works for most use cases.short: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications.
Origins allowed to embed this ceremony in an iframe.These values set the
frame-ancestors directive in the ceremony’s Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, https://app.example.com). Wildcards are supported (for example, https://*.example.com). For all available options, see the frame-ancestors documentation.Defaults to an empty list ([]), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use ["*"].Only the origin (scheme and host) is used. Paths are ignored.
Controls whether the completed deliverable is automatically emailed to this recipient.
| Value | Description |
|---|---|
email | The completed deliverable is delivered to this recipient by email. This is the default for signers. |
none | The completed deliverable is not emailed. Your application is responsible for distributing the deliverable. |
The signature methods available to the signer. The first item in the array is shown as the default.
If not specified, both
| Option | Description |
|---|---|
typed | The signer types their name. It is pre-filled from the recipient’s name property. |
drawn | The signer draws their signature using a mouse, stylus, or touchscreen. |
typed and drawn are available, with typed shown first.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 deprecated. Use the
ceremony object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility.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.
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.Show Standard Deliverable
Show Standard Deliverable
The standard deliverable includes an audit log. To get signed documents without an audit log, use the simple deliverable instead.
A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters.
The type of the deliverable.
standard: Includes the signed documents and an audit log with a certificate of completion. This is the default.simple: Includes the signed documents only, without an audit log.
standard.The language for system-generated text in the audit log, including labels and the certificate of completion. Does not affect the content of the signed documents.Supported values:
en (English), es (Spanish), fr (French), it (Italian), pt (Portuguese), de (German), zh (Chinese Simplified), hu (Hungarian).Defaults to the envelope language.The timezone used for timestamps in the audit log. Must be a valid IANA Time Zone Database identifier (e.g.,
America/New_York, Europe/London). Does not affect timestamps inside the signed documents.Defaults to the envelope timezone.The format for timestamps in the audit log. Uses MomentJS format tokens (e.g.,
MM/DD/YYYY HH:mm:ss). Does not affect timestamps inside the signed documents.Defaults to the envelope timestamp format.The keys of the documents to include in the deliverable. By default, all documents in the envelope are included.Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys.
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 does not include an audit log. To get signed documents with an audit log, use the standard deliverable instead.
A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one.Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters.
The type of the deliverable.
standard: Includes the signed documents and an audit log with a certificate of completion. This is the default.simple: Includes the signed documents only, without an audit log.
simple.The keys of the documents to include in the deliverable. By default, all documents in the envelope are included.Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys.
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.
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.
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
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).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.
Show Sender
Show Sender
The name of the sender, displayed to recipients in emails and the signing ceremony. Maximum 500 characters.
The email address of the sender, shown to recipients for reference. Maximum 320 characters.
The organization name of the sender, displayed to recipients alongside the sender’s name and email. Defaults to
null. Maximum 500 characters.Customizes the visual appearance of the signing ceremony and recipient emails. Branding does not affect internal notifications or signed documents.Learn more about branding.
Show Branding
Show Branding
The URL of the logo image displayed in the header of emails and the signing ceremony. Must be a PNG file uploaded to the Library. Defaults to
null.Only files uploaded to your account’s Library are accepted. Direct external URLs are not supported.The accent color applied to buttons in emails and the signing ceremony. Specified as a hex color code (for example,
#2463eb). Defaults to #2463eb.The color must have a contrast ratio of at least 4.5:1 against white, following WCAG guidelines. If the color does not meet this requirement, the API returns an error with a suggested compliant alternative.Additional customization for emails sent to recipients, including footer text and logo alignment.
Show Email options
Show Email options
A custom footer included at the bottom of all recipient emails for this envelope, after SignatureAPI’s standard footer content. Use it for disclaimers, privacy notices, or contact information. Defaults to
null.Supports a subset of Markdown: **bold**, *italic*, and \n\n for paragraph breaks. Maximum 10,000 characters.The horizontal alignment of the logo in recipient emails. Accepted values are
left, center, and right. Defaults to left.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 a201 Created status code along with an envelope object on success, or an error otherwise.
Copy
Ask AI
// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
// Content-Type: application/json
{
"title": "Service Agreement",
"message": "Please review the privacy policy 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
// HTTP Status Code 201
{
"id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"title": "Exploration Agreement",
"label": "Exploration Agreement for Order Ref. 25005",
"message": "Please review the agreement and provide your 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": "MM/DD/YYYY HH:mm:ss",
"attestation": "none",
"branding": {
"logo": "https://api.signatureapi.com/v1/uploads/upl_3jBYlxa9gv0fGLzFAnfwxe",
"accent_color": "#9810fa",
"email": {
"from": "noreply@signatureapi.com",
"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": "Exploration 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": "jane@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": "2025-12-31T12:00:01.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",
"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": ["drawn"],
"completed_at": null,
"status_updated_at": "2025-12-31T12:00:01.000Z"
}
],
"deliverable": {
"id": "del_1T7If8GgrTOf7zBVPaJf2e",
"name": null,
"envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
"type": "standard",
"status": "pending",
"url": null,
"language": "en",
"timezone": "UTC",
"timestamp_format": "MM/DD/YYYY HH:mm:ss",
"included_documents": null,
"password": null,
"created_at": "2025-12-31T12:00:00.000Z",
"generated_at": null
},
"captures": {},
"snapshot_url": null,
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": null
}
Was this page helpful?
⌘I
Assistant
Responses are generated using AI and may contain mistakes.