POST
/
v1
/
envelopes
// 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
}
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.
recipients
array of Recipients
required
People that signs the documents in an envelope.

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