Relationships
An envelope:- Has one or more recipients
- Has one or more documents
- Has zero or one deliverables
Attributes
The unique identifier of the 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.Custom label given to the envelope for easier identification. Labels are for
internal use and are not shown to recipients.
A message to include in emails to recipients.The 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 current status of the envelope.Available options:
processing, in_progress, completed, failed, canceledThe mode affects both legal status and billing of an envelope. Live mode envelopes are legally binding and incur
charges, whereas test mode envelopes are non-binding and are not counted towards billing.Available options:
live, testThe 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.
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.
A collection of documents to be signed.
Show PDF Document
Show PDF Document
The unique identifier of the document.
The unique identifier of the envelope.
The title of the document. It may be shown to recipients.
The number of pages in the document.
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 is 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 unique identifier of the document.
The unique identifier of the envelope.
The title of the document. It may be shown to recipients.
The number of pages in the document.
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 is 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
The unique identifier of the recipient.
The unique identifier of the envelope.
Specifies the type of recipient. The only available option is
signer (we will add more recipient types soon).For signers, the type is 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 current status of a recipient.Available options are
pending, awaiting, sent, completed, rejected, soft_bounced, hard_bounced, failed, and replaced.The current ceremony for the recipient.
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 is 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 is 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 is 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.
The URL where recipients can access and complete the signing ceremony. This can be embedded in a web or mobile app, or shared by other means.This property will be
null in the following cases:- The recipient is expected to access the ceremony via an internal delivery method (for example, authentication via
email_link). - The ceremony is not currently active (for example, it has been completed, revoked, or declined).
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"].Time at which the recipient completed (e.g., signed) the envelope, in format. This value can be
null if the recipient has not yet completed.Time at which the status was last updated, in format.
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.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.
The that was automatically generated when the envelope was completed.
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 unique identifier of the deliverable.
The unique identifier of the envelope.
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.
The current status of the deliverable.Available options are
pending, processing, generated, and failed.pending: The deliverable is pending generation while the envelope is not yet completed.processing: The envelope is completed and the deliverable is being generated.generated: The deliverable has been generated. The object includes aurlfor download.failed: The deliverable failed to be generated.
The URL for downloading the deliverable. This link is intended for immediate use, as it expires after a short
period.
- By default, this is a short‑lived, pre‑signed URL that requires no additional authentication.
- The URL expires after 1 hour. If the link has expired, retrieve the deliverable again to get a new URL.
- If your account uses authenticated URLs (for example, for HIPAA compliance), you must access this URL with your API key like any other API request. Authenticated URLs do not expire.
null until the deliverable is generated.Time at which the deliverable was created, in ISO 8601 format.
Time at which the deliverable was generated, in ISO 8601 format. This value can be
null until the deliverable is generated.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 unique identifier of the deliverable.
The unique identifier of the envelope.
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.
The current status of the deliverable.Available options are
pending, processing, generated, and failed.pending: The deliverable is pending generation while the envelope is not yet completed.processing: The envelope is completed and the deliverable is being generated.generated: The deliverable has been generated. The object includes aurlfor download.failed: The deliverable failed to be generated.
The URL for downloading the deliverable. This link is intended for immediate use, as it expires after a short
period.
- By default, this is a short‑lived, pre‑signed URL that requires no additional authentication.
- The URL expires after 1 hour. If the link has expired, retrieve the deliverable again to get a new URL.
- If your account uses authenticated URLs (for example, for HIPAA compliance), you must access this URL with your API key like any other API request. Authenticated URLs do not expire.
null until the deliverable is generated.Time at which the deliverable was created, in ISO 8601 format.
Time at which the deliverable was generated, in ISO 8601 format. This value can be
null until the deliverable is generated.Contains the values collected from input fields completed by recipients.
Time at which the envelope was created, in format.
Time at which the envelope was completed by all recipients, in format. This value can be
null until completion.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.",
"status": "completed",
"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"
},
"topics": [
"sales",
"project_blue"
],
"metadata": {
"customer_ref": "x9550501",
"account_annual_revenue": "$4,500,000"
},
"documents": [
{
"id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"title": "Dummy Agreement",
"page_count": 2,
"url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx",
"format": "docx",
"data": {
"date": "December 31st, 2025",
"showAlert": true,
"serviceProvider": {
"name": "Jane Smith",
"organization": "ACME Global, Inc."
},
"client": {
"name": "Michael J. Miller",
"organization": "Miller Industries"
}
},
"places" : [
{
"key": "provider_signs_here",
"type": "signature",
"recipient_key": "service_provider"
},
{
"key": "client_signs_here",
"type": "signature",
"recipient_key": "client"
}
]
}
],
"recipients": [
{
"id": "re_26w2VVV5JVm4j459TY5BNM",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "provider",
"name": "Emily Johnson",
"email": "emily@example.com",
"status": "completed",
"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": "2025-12-31T15:00:00.000Z",
"status_updated_at": "2025-12-31T15:00:00.000Z"
},
{
"id": "re_38UVwrWdCqX5kqeKFJUTtf",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"type": "signer",
"key": "client",
"name": "Michael Taylor",
"email": "michael@example.com",
"status": "completed",
"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": "2025-12-31T14:00:00.000Z",
"status_updated_at": "2025-12-31T14:00:00.000Z"
}
],
"deliverable": {
"id": "del_1T7If8GgrTOf7zBVPaJf2e",
"envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
"status": "generated",
"type": "standard",
"url": "https://s3.us-east-2.amazonaws.com/signatureapi-vault-dev/envelopes/52872f0e...",
"language": "en",
"timezone": "America/New_York",
"timestamp_format": "MM/DD/YYYY HH:mm:ss"
},
"created_at": "2025-12-31T12:00:00.000Z",
"completed_at": "2025-12-31T15:00:00.000Z"
}