Create an envelope

This operation creates an envelope and starts the signing process, sending the documents to the recipients.

Body Parameters

Core Parameters

These are the essential parameters required to define and send an envelope.

title

string

required

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.

documents

array of documents

required

A collection of documents to be signed.

Show PDF Document

title

string

The title of the document. It may be shown to recipients.

url

string

required

The URL where the document or template is located. Learn more about providing files to SignatureAPI.

format

enum

required

The format of the document or template. Available options are pdf and docx.For PDF documents the format must be pdf.

fixed_positions

array of fixed positions

Show fixed position

key

string

required

A user-provided key that identifies a place within a document.It must match to one of the keys in the document’s place list.

page

number

required

The page number for this position.

top

number

required

The distance, in points (or 1/72th of an inch), from the top border of the page to the position.

left

number

required

The distance, in points (or 1/72th of an inch), from the left border of the page to the position.

places

array of places

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

A space where the recipient, identified by the recipient_key, needs to sign.

type

enum

required

Specifies the type of place.For a signature place, the value must be signature.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

height

number

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

A space where the recipient, identified by the recipient_key, needs to write their initials.

type

enum

required

Specifies the type of place.For an initials place, the value must be initials.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

height

number

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

An arbitrary text string.

type

enum

required

Specifies the type of place.For a text place, the value must be text.

key

string

required

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.

value

string

required

The text content.

font_size

number

The font size in points.Must be between 1 and 144. The default is 12.

font_color

string

The font color in hexadecimal notation. Default is #000000 (black).

Show text input place

A text input field to ask recipients to enter text.

type

enum

required

Specifies the type of place.For a text input place, the value must be text_input.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

capture_as

string

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.

hint

string

A tooltip message displayed over the input text field during the signing ceremony.Learn more in Hints and Prompts.

prompt

string

A placeholder message shown inside the input text field during the signing ceremony.Learn more in Hints and Prompts.

requirement

enum

Specifies whether the recipient must fill this field to complete the signing ceremony.Possible values are required or optional. The default is required.

format

enum or regex

Defines the validation format for the user’s input.Accepted values are email or zipcode-us. Alternatively, a regular expression can be used, enclosed in forward slashes.Learn more in Format Validation.

format_message

string

The message displayed when the user’s input does not match the required format.Learn more in Format Validation -> Adding a Custom Message.

width

number

The initial width of the text input place in .Must be between 30 and 540. The default is 30.

font_size

number

The font size in .Must be between 6 and 12. The default is 12.

Show checkbox place

A checkbox field to ask recipients to check a box.

type

enum

required

Specifies the type of place.For a checkbox place, the value must be checkbox.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

capture_as

string

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.

symbol

enum

The symbol to display in the checkbox when it is checked.Available options are check and xmark. The default is check.

requirement

enum

Specifies whether the recipient must check this box to complete the signing ceremony.Possible values are required or optional. The default is optional.

height

number

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

The date when the recipient, identified by the recipient_key, completed (for example, signed) the envelope.

type

enum

required

Specifies the type of place.For this kind of place, the value must be recipient_completed_date.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

date_format

string

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

The date when the envelope was completed.

type

enum

required

Specifies the type of place.For this kind of place, the value must be envelope_completed_date.

key

string

required

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.

date_format

string

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

title

string

The title of the document. It may be shown to recipients.

url

string

required

The URL where the document or template is located. Learn more about providing files to SignatureAPI.

format

enum

required

The format of the document or template. Available options are pdf and docx.For DOCX documents the format must be docx.

data

object

The data to fill the template with.Object keys must be alphanumeric.

fixed_positions

array of fixed positions

Show fixed position

key

string

required

A user-provided key that identifies a place within a document.It must match to one of the keys in the document’s place list.

page

number

required

The page number for this position.

top

number

required

The distance, in points (or 1/72th of an inch), from the top border of the page to the position.

left

number

required

The distance, in points (or 1/72th of an inch), from the left border of the page to the position.

places

array of places

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

A space where the recipient, identified by the recipient_key, needs to sign.

type

enum

required

Specifies the type of place.For a signature place, the value must be signature.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

height

number

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

A space where the recipient, identified by the recipient_key, needs to write their initials.

type

enum

required

Specifies the type of place.For an initials place, the value must be initials.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

height

number

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

An arbitrary text string.

type

enum

required

Specifies the type of place.For a text place, the value must be text.

key

string

required

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.

value

string

required

The text content.

font_size

number

The font size in points.Must be between 1 and 144. The default is 12.

font_color

string

The font color in hexadecimal notation. Default is #000000 (black).

Show text input place

A text input field to ask recipients to enter text.

type

enum

required

Specifies the type of place.For a text input place, the value must be text_input.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

capture_as

string

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.

hint

string

A tooltip message displayed over the input text field during the signing ceremony.Learn more in Hints and Prompts.

prompt

string

A placeholder message shown inside the input text field during the signing ceremony.Learn more in Hints and Prompts.

requirement

enum

Specifies whether the recipient must fill this field to complete the signing ceremony.Possible values are required or optional. The default is required.

format

enum or regex

format_message

string

The message displayed when the user’s input does not match the required format.Learn more in Format Validation -> Adding a Custom Message.

width

number

The initial width of the text input place in .Must be between 30 and 540. The default is 30.

font_size

number

The font size in .Must be between 6 and 12. The default is 12.

Show checkbox place

A checkbox field to ask recipients to check a box.

type

enum

required

Specifies the type of place.For a checkbox place, the value must be checkbox.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

capture_as

string

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.

symbol

enum

The symbol to display in the checkbox when it is checked.Available options are check and xmark. The default is check.

requirement

enum

Specifies whether the recipient must check this box to complete the signing ceremony.Possible values are required or optional. The default is optional.

height

number

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

The date when the recipient, identified by the recipient_key, completed (for example, signed) the envelope.

type

enum

required

Specifies the type of place.For this kind of place, the value must be recipient_completed_date.

key

string

required

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.

recipient_key

string

required

A user-provided key that identifies a recipient within an envelope.It must match to one of the keys in the envelope’s recipient list.

date_format

string

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

The date when the envelope was completed.

type

enum

required

Specifies the type of place.For this kind of place, the value must be envelope_completed_date.

key

string

required

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.

date_format

string

Defines the format of the date, using MomentJS date format definitions.The default format is D MMM YYYY, which outputs as 31 Dec 2025.

recipients

array of recipients

required

People that signs the documents in an envelope.

Show Signer

type

enum

required

Specifies the type of recipient. The only available option is signer (we will add more recipient types soon).For signers, the type must be signer.

key

string

required

A unique identifier you assign to each recipient in the envelope.It’s used to match recipients with the places they should interact with (like signature fields) and to identify them in events and webhook notifications.It must be unique within the envelope, contain up to 32 lowercase letters or numbers, and start with a letter.

name

string

required

The name of the recipient.

string

required

The email address of the recipient.

ceremony

object

The first ceremony to create for the recipient.If no ceremony is provided, a ceremony with email_link authentication will be created.

Show Ceremony

authentication

array of authentication object

required

Show Email Link Authentication

With link via email authentication, the recipient receives an email with a link to initiate the ceremony, sent by SignatureAPI.

type

enum

required

Specifies the type of authentication. The available options are email_link, email_code, and custom.For link via email authentication, this type must be email_link.

Show Email Code Authentication

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.

type

enum

required

Specifies the type of authentication. The available options are email_link, email_code, and custom.For email code authentication, this type must be email_code.

Show Custom Authentication

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.

type

enum

required

Specifies the type of authentication. The available options are email_link, email_code, and custom.For custom authentication, this type must be custom.

provider

string

required

The name of the authentication provider, such as your company or application. This value will appear in the envelope’s audit logs.

data

object

required

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.

redirect_url

string

A URL to redirect the recipient to after a ceremony is finished.Learn more in Redirect URL.

url_variant

enum

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.

embeddable_in

array of strings

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.

To ensure compatibility, we consider only the origin (scheme and host) of the URL and exclude the path.

delivery_type

enum

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.

signature_options

array of enum

An array that defines which signature types a recipient can use, with the first item shown as the default option during signing.Available values for the array items are typed and drawn. The default value for this property is ["typed", "drawn"].

Show Deprecated Fields

ceremony_creation

enum

deprecated

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.

deliverable

deliverable object

Configuration for the that will be automatically generated when the envelope is completed.This deliverable is automatically sent to all recipients via email. To prevent automatic delivery, set a recipient’s delivery_method to none and distribute it another way.If no deliverable is provided, a Standard Deliverable will be automatically generated.

Show Standard Deliverable

The Standard Deliverable includes the signed documents along with an audit log. If you just need the signed documents, use the Simple Deliverable instead.

type

enum

required

The type of the deliverable.Available options are standard and simple. The default is standard.

standard: Includes all documents and an audit log
simple: Includes only the documents without an audit log

For standard deliverables, the type is standard.

language

enum

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.

timezone

string

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.

timestamp_format

string

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.

password

string

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)

When returned in API responses, the password value is masked for security (displayed as ********).

Password protection is available upon request. Contact support to enable this feature.

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.

type

enum

required

The type of the deliverable.Available options are standard and simple. The default is standard.

standard: Includes all documents and an audit log
simple: Includes only the documents without an audit log

For simple deliverables, the type is simple.

password

string

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)

When returned in API responses, the password value is masked for security (displayed as ********).

Password protection is available upon request. Contact support to enable this feature.

Envelope Customization

These parameters let you tailor the signing process to meet specific workflow or user requirements.

message

string

A message to include in emails to recipients.

routing

enum

The order in which recipients sign the envelope. It can be sequential, where recipients sign one after another, or parallel, where all recipients can sign simultaneously. The default is sequential.Learn more about Recipient Routing

language

string

The language for the signer interface and related emails.Refer to the list of available languages. The default value is en (English).

timezone

string

The time zone for this envelope.

timestamp_format

string

The timestamp format for this envelope.

sender

object

The sender of the envelope.

Show Sender

name

string

The name of the sender of the envelope.

string

The email address of the sender of the envelope.

organization

string

The organization of the sender of the envelope.

attestation

enum

Specifies an attestation for the envelope, as required by certain country regulations. In most cases—including the US and EU member states—no special attestation is needed. For more information, see Attestation.

Envelope Details

These parameters help annotate and organize the envelope.

label

string

Custom label given to the envelope for easier identification. Labels are for internal use and are not shown to recipients.

topics

array of strings

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.

metadata

object

A set of up to 10 custom key-value pairs containing metadata about the envelope.

Returns

Returns a 201 Created status code along with an envelope object after successful creation, or an error otherwise.

// POST https://api.signatureapi.com/v1/envelopes
// X-API-Key: key_test_...
{
  "title": "Dummy Agreement",
  "message": "Please review the privacy policy at your convenience and provide your signature.",
  "documents": [
    {
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
      "format": "pdf",
      "places" : [
        {
          "key": "signer_signs_here",
          "type": "signature",
          "recipient_key": "visitor"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "visitor",
      "name": "John Doe",
      "email": "john@example.com"
    }
  ]
}

{
  "id": "55072f0e-b919-4d69-89cd-e7e56af00530",
  "title": "Dummy Agreement",
  "label": "Dummy Agreement for Order Ref. 25005",
  "message": "Please review the agreement at your convenience and provide your electronic signature.",
  "topics": [
    "sales",
    "project_blue"
  ],
  "metadata": {
    "customer_ref": "x9550501",
    "account_annual_revenue": "$4,500,000"
  },
  "status": "processing",
  "mode": "live",
  "routing": "sequential",
  "language": "en",
  "timezone": "UTC",
  "timestamp_format": "DD/MM/YYYY HH:mm:ss",
  "sender": {
    "name": "Jennifer Lee",
    "email": "jennifer@example.com",
    "organization": "Acme Enterprises"
  },
  "documents": [
    {
      "id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
      "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
      "title": "Dummy Agreement",
      "page_count": 2,
      "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx",
      "format": "docx",
      "data": {
        "date": "December 31st, 2025",
        "showAlert": true,
        "serviceProvider": {
          "name": "Jane Smith",
          "organization": "ACME Global, Inc."
        },
        "client": {
          "name": "Michael J. Miller",
          "organization": "Miller Industries"
        }
      },
      "places" : [
        {
          "key": "provider_signs_here",
          "type": "signature",
          "recipient_key": "service_provider",
          "height": 60
        },
        {
          "key": "client_signs_here",
          "type": "signature",
          "recipient_key": "client",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_26w2VVV5JVm4j459TY5BNM",
      "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
      "type": "signer",
      "key": "service_provider",
      "name": "Jane Smith",
      "email": "emily@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link"
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "url": null,
        "url_variant": "standard"
      },
      "delivery_type": "email",
      "ceremony_creation": "automatic",
      "signature_options": ["typed", "drawn"],
      "completed_at": null,
      "status_updated_at": "2025-12-31T15:00:00.000Z"
    },
    {
      "id": "re_38UVwrWdCqX5kqeKFJUTtf",
      "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
      "type": "signer",
      "key": "client",
      "name": "Michael J. Miller",
      "email": "michael@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link"
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "url": null,
        "url_variant": "standard"
      },
      "delivery_type": "email",
      "ceremony_creation": "automatic",
      "signature_options": ["drawn"],
      "completed_at": null,
      "status_updated_at": "2025-12-31T14:00:00.000Z"
    }
  ],
  "deliverable": {
    "id": "del_1T7If8GgrTOf7zBVPaJf2e",
    "envelope_id": "55072f0e-b919-4d69-89cd-e7e56af00530",
    "status": "processing",
    "type": "standard",
    "language": "en",
    "timezone": "UTC",
    "timestamp_format": "DD/MM/YYYY hh:mm:ss",
    "url": null,
    "password": null,
    "created_at": "2025-12-31T12:00:00.000Z",
    "generated_at": null
  },
  "created_at": "2025-12-31T12:00:00.000Z",
  "completed_at": null
}

Introduction

Reference

Explore

Envelopes

Recipients

Documents

Places

Deliverables

Ceremonies

Events

Uploads

Senders

Body Parameters

Core Parameters

Envelope Customization

Envelope Details

Returns

Introduction

Reference

Explore

Envelopes

Recipients

Documents

Places

Deliverables

Ceremonies

Events

Uploads

Senders

​Body Parameters

​Core Parameters

​Envelope Customization

​Envelope Details

​Returns

Body Parameters

Core Parameters

Envelope Customization

Envelope Details

Returns