Envelope Create

Creates a signature envelope from one or more uploaded documents, the recipients who must act on it, and the fields they complete or sign. The envelope is created in Draft status and nothing is sent to recipients by this call — send it separately with signatures-envelope-send.

Uploading the documents is a mandatory first step: every document must already be in Storage before this call. Upload each one with signatures-document-upload, which returns a storage id, then reference that id in documents[].urn with documents[].loadMethod set to storage. There is no way to send document content inline — no base64 field and no multipart variant — so an envelope cannot be created in a single request.

Storage keeps an uploaded document for 24 hours, so the upload and this call have to happen within that window. If an id does not resolve — wrong id, never uploaded, or the window has passed — the whole request fails with a 500 carrying FILE_NOT_EXISTS_IN_STORAGE, and no envelope is created.

A .docx document is converted to PDF while the envelope is created, because signing operates on PDF only, and anchor text is resolved against that converted PDF.

The parts of the request are linked by client-assigned reference ids rather than server ids, because no server ids exist yet: you choose documents[].referenceDocumentId, recipients[].referenceSignerId and signGroups[].referenceSignGroupId, each unique within the request, and fields[] points at them. The response returns the server-generated id for every object created.

Some failures depend on the subscription rather than on the request: multi-factor authentication on a recipient, attachment fields, digital signature fields, the viewer role and the inpersonsigner role each have their own error code when the plan does not include them. See the 400 response for the full list of error codes.

This operation is metered. A successful call reports one unit of the envelopes-created dimension, returned in consumption.

Authorization

AuthorizationBearer <token>

JWT token to authenticate the request.

In: header

X-Api-Key<token>

API key, sent as a request header.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body for creating or updating a signature envelope. It follows the standard request envelope: an optional externalContext supplied by the caller and echoed back unchanged, alongside the named sections that describe the envelope — documents, recipients, fields, signGroups and envelope.

The sections are linked by client-assigned reference ids rather than server ids, because no server ids exist until the envelope is created. Each document, recipient and sign group carries an id you choose, and fields points at those ids. Every reference id must be unique within the request — duplicates are rejected with DUPLICATE_REFERENCE_DOCUMENT_ID, DUPLICATE_REFERENCE_RECIPIENT_ID or DUPLICATE_REFERENCE_SIGNGROUP_ID. The response returns the server-generated id for every object created.

documents*array<>

The documents the envelope is built from. Mandatory, and must contain at least one entry — an absent list is rejected with NO_DOCUMENTS, an empty one with DOCUMENT_LIST_CANNOT_BE_EMPTY.

Items1 <= items

fields?array<>

The fields placed on the documents for recipients to complete or sign. Optional.

recipients*array<>

The people who receive the envelope and what each of them may do with it. Mandatory, and must contain at least one entry — an absent list is rejected with NO_RECIPIENTS, an empty one with RECIPIENT_LIST_CANNOT_BE_EMPTY.

Items1 <= items

signGroups?array<>

Groups of recipients that share a role, a position in the signing order and a set of fields, so a field can be assigned to the group rather than to one named person. Optional.

envelope?

Settings that apply to the envelope as a whole: the notification email, the sender shown to recipients, signing order, expiry, reminders and notifications.

externalContext?unknown

Arbitrary JSON object supplied by the caller and echoed back unchanged in the response envelope, for correlating a request with its response. Its shape is not validated or interpreted.

Response Body

`application/json`

curl -X POST "https://example.com/signatures/envelope/create" \  -H "Content-Type: application/json" \  -d '{    "documents": [      {        "referenceDocumentId": 1,        "name": "Master Services Agreement",        "loadMethod": "Storage",        "urn": "b6a5f346-6b60-4c1a-9d55-782651280abc",        "externalContext": {          "id": "123"        }      }    ],    "recipients": [      {        "referenceSignerId": 1,        "name": "Jane Doe",        "email": "jane.doe@example.com",        "role": "signer",        "mandatory": true,        "externalContext": {          "id": "456"        }      },      {        "referenceSignerId": 2,        "referenceSignGroupId": 1,        "name": "Alice Nguyen",        "email": "alice@example.com"      }    ],    "signGroups": [      {        "referenceSignGroupId": 1,        "name": "Legal review",        "role": "signer",        "mandatory": true      }    ],    "fields": [      {        "referenceSignerId": 1,        "referenceDocumentId": 1,        "name": "mds_signature_customer",        "type": "signature",        "page": 1,        "height": 48,        "width": 180,        "positionX": 72,        "positionY": 640,        "isRequired": true,        "tooltip": "Sign here to accept the agreement."      },      {        "referenceSignGroupId": 1,        "referenceDocumentId": 1,        "name": "mds_signature_legal",        "type": "signature",        "anchorString": "@countersigned_by@",        "isRequired": true      },      {        "referenceSignerId": 1,        "referenceDocumentId": 1,        "name": "mds_customer_reference",        "type": "text",        "page": 1,        "height": 24,        "width": 220,        "positionX": 72,        "positionY": 580,        "isRequired": true,        "tooltip": "Your internal purchase order number.",        "properties": {          "fontFamily": "Arial",          "fontSize": 11,          "color": "#1f2937",          "textAlign": "left",          "placeholder": "PO number",          "regexValidation": "^[A-Z]{2}[0-9]{6}$",          "regexValidationMessage": "Enter two letters followed by six digits, for example AB123456."        }      }    ],    "envelope": {      "subject": "Master Services Agreement for signature",      "message": "Please review and sign the attached agreement.",      "senderName": "Contracts Team",      "senderEmail": "ops@example.com",      "isSignOrder": false,      "expireInDays": 5,      "alertDaysBeforeExpiry": 2,      "firstReminderDays": 3,      "repeatingReminderDays": 2,      "notifyWhenOpened": true,      "notifyWhenSigned": true,      "locale": "en-GB",      "timezone": "Europe/London"    },    "externalContext": {      "id": "789"    }  }'

{  "result": {    "statusCode": 201,    "message": "Created",    "data": {      "envelope": {        "id": "66e0fdcc-3b59-46e8-aef9-f55cb2cad859",        "uploadDate": "2026-09-17T09:14:22.000Z",        "status": "Draft"      },      "documents": [        {          "id": "60effbcd-ce0c-40a3-8836-758432627548",          "externalContext": {            "id": "123"          }        }      ],      "recipients": [        {          "id": "19c0b59d-3a02-48fa-9b6a-0582e16254d9",          "externalContext": {            "id": "456"          }        },        {          "id": "8d41b2ce-7f05-4a9e-9b3c-2e6a0c5d1487",          "externalContext": ""        }      ],      "signGroups": [        {          "id": "3312f927-cdde-4a2b-8c8d-50e70ba12402"        }      ],      "fields": [        {          "id": "af2dedac-aa9b-4355-9e43-c19839d26013",          "recipientId": "19c0b59d-3a02-48fa-9b6a-0582e16254d9",          "signGroupId": "",          "documentId": "60effbcd-ce0c-40a3-8836-758432627548"        },        {          "id": "c9b7e05a-3d18-4f62-8a44-71d0e2b9635f",          "recipientId": "",          "signGroupId": "3312f927-cdde-4a2b-8c8d-50e70ba12402",          "documentId": "60effbcd-ce0c-40a3-8836-758432627548"        },        {          "id": "5e2a91f7-6c43-4b08-9d57-8fa3c04e71b2",          "recipientId": "19c0b59d-3a02-48fa-9b6a-0582e16254d9",          "signGroupId": "",          "documentId": "60effbcd-ce0c-40a3-8836-758432627548"        }      ]    }  },  "origin": "POST https://api.doctavian.com/v1/signatures/envelope/create",  "dateTime": "2026-07-20T12:00:00.000Z",  "consumption": [    {      "dimension": "envelopes-created",      "value": 1    }  ],  "externalContext": {    "id": "789"  },  "userId": "12f0a7b9-ec67-4232-863d-46e3d4e5ba44",  "operationId": "7b1de42c0f9a4e6cb83d5177ae0c2f31"}

{  "error": {    "statusCode": 400,    "message": "The field 'mds_signature1' has neither an anchor string nor a complete set of position values.",    "innerErrors": [      {        "code": "ANCHOR_NOT_PROVIDED_POSITION_REQUIRED",        "message": "The field 'mds_signature1' has neither an anchor string nor a complete set of position values.",        "userMessage": "A field could not be placed on the document. Provide either anchor text or the page and position for every field."      }    ]  },  "origin": "POST https://api.doctavian.com/v1/signatures/envelope/create",  "dateTime": "2026-07-20T12:00:00.000Z",  "userId": "29eeeed1-6575-4cd6-87eb-0c9f978da19a",  "operationId": "8c4018a60ae91bb5346e291890d45210"}

{  "error": {    "message": "Envelope not found.",    "statusCode": 500,    "innerErrors": [      {        "code": "ENVELOPE_ID_INVALID",        "message": "Envelope not found.",        "userMessage": "Envelope not found."      }    ]  },  "origin": "POST https://api.doctavian.com/v1/signatures/envelope/create",  "dateTime": "2026-07-20T12:00:00.000Z",  "userId": "89d18e31-82ef-4c1d-ad0b-008b0227b65e",  "operationId": "888e695a8c62bab6cd36f7b63e4b714c"}

Authorization

Request Body

Response Body

201application/json

400application/json

500application/json

`application/json`

`application/json`

`application/json`