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 place within the document in . The width is calculated based on a 5:2 ratio.The default height is 60 points.

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 place within the document in . The width is the same as the height.The default height is 60 points.

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. 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.

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.

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 place within the document in . The width is calculated based on a 5:2 ratio.The default height is 60 points.

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 place within the document in . The width is the same as the height.The default height is 60 points.

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. 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.

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.

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_creation

enum

How the ceremony is created for the recipient.Available options are automatic and manual. The default is automatic.

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"].

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 parallel, where all recipients can sign simultaneously, or sequential, where recipients sign one after another. The default is parallel.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": "52872f0e-b919-4d69-89cd-e7e56af00548",
      "title": "Dummy Agreement",
      "page_count": 2,
      "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/dummy.docx",
      "format": "docx",
      "data": {
        "date": "December 31st, 2025",
        "showAlert": true,
        "serviceProvider": {
          "name": "Jane Smith",
          "organization": "ACME Global, Inc."
        },
        "client": {
          "name": "Michael J. Miller",
          "organization": "Miller Industries"
        }
      },
      "places" : [
        {
          "key": "provider_signs_here",
          "type": "signature",
          "recipient_key": "service_provider",
          "height": 60
        },
        {
          "key": "client_signs_here",
          "type": "signature",
          "recipient_key": "client",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_26w2VVV5JVm4j459TY5BNM",
      "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
      "type": "signer",
      "key": "service_provider",
      "name": "Jane Smith",
      "email": "emily@example.com",
      "status": "pending",
      "ceremony_creation": "automatic",
      "delivery_type": "email",
      "signature_options": ["typed", "drawn"],
      "completed_at": null,
      "status_updated_at": "2025-12-31T15:00:00.000Z"
    },
    {
      "id": "re_38UVwrWdCqX5kqeKFJUTtf",
      "envelope_id": "52872f0e-b919-4d69-89cd-e7e56af00548",
      "type": "signer",
      "key": "client",
      "name": "Michael J. Miller",
      "email": "michael@example.com",
      "status": "pending",
      "ceremony_creation": "automatic",
      "delivery_type": "email",
      "signature_options": ["drawn"],
      "completed_at": null,
      "status_updated_at": "2025-12-31T14:00:00.000Z"
    }
  ],
  "deliverable": null,
  "created_at": "2025-12-31T12:00:00.000Z",
  "completed_at": null
}

Introduction

Reference

Explore

Envelopes

Recipients

Documents

Places

Deliverables

Ceremonies

Events

Files

Senders

Body Parameters

Core Parameters

Envelope Customization

Envelope Details

Returns

Introduction

Reference

Explore

Envelopes

Recipients

Documents

Places

Deliverables

Ceremonies

Events

Files

Senders

​Body Parameters

​Core Parameters

​Envelope Customization

​Envelope Details

​Returns

Body Parameters

Core Parameters

Envelope Customization

Envelope Details

Returns