Create envelope

Creates a new envelope containing one or more documents and associated signers. The envelope can be used for document signing or other related workflows. Upon creation, the envelope will be assigned a unique identifier for future operations such as tracking, signing, or editing. Ensure all required fields, including documents and signers, are provided in the request payload.

Request

Authorization

Add parameter in header

x-api-token

Example:

x-api-token: ********************

Body Params application/json

vaultId

string <uuid>

required

Id of the vault where the envelope will be created

>= 1 characters

name

string

required

Name of the envelope

>= 2 characters<= 200 characters

privateDescription

string | null

optional

Private description of the envelope

<= 4000 characters

publicDescription

string | null

optional

Public description of the envelope

<= 4000 characters

message

string | null

optional

Message of the envelope, which will be send to the signers via email

<= 4000 characters

reviewReminder

boolean

required

Indicates if review reminders should be sent to the signers

expiresAtUtc

string <date-time> | null

optional

Date and time when the envelope will expire in UTC

expirationReminder

boolean

optional

Indicates if expiration reminders should be sent to the signers

toBePublishedAtUtc

string <date-time> | null

optional

Date and time when the envelope will be published in UTC

language

enum<string>

required

Language of the envelope

Allowed values:

EnUsPtBr

markupOrientation

enum<string>

required

Markup orientation of the envelope

Allowed values:

NoneBottomTopLeftRight

signInOrder

boolean

required

Indicates if the signers should sign in order

signers

array[object (CreateEnvelopeSignerApiRequest) {19}] | null

optional

List of signers

name

string

required

Name of the signer

>= 2 characters<= 200 characters

string | null

optional

Email of the signer

Match pattern:

^([\w\.\-]+)@([\w\-]+)((\.(\w){2,3})+)$

role

enum<string>

required

Role of the signer

Allowed values:

SignApproveRecognizeTestifyConfirmReceivingEndorseInBlackEndorseInWhiteConfirm

title

string | null

optional

Title of the signer, e.g. Lawyer, Company Director, etc.

<= 200 characters

shouldEnforceEmailValidation

boolean

optional

Indicates if the email OTP validation should be enforced for the signer

shouldEnforceSmsValidation

boolean

required

Indicates if the SMS OTP validation should be enforced for the signer

shouldEnforceWhatsAppValidation

boolean

required

Indicates if the WhatsApp OTP validation should be enforced for the signer

shouldEnforcePixValidation

boolean

required

Indicates if the PIX OTP validation should be enforced for the signer

shouldEnforceGeolocationValidation

boolean

required

Indicates if the geolocation validation should be enforced for the signer

shouldAllowCustomDigitalCertificateValidation

boolean

required

Indicates if the custom digital certificate validation should be allowed for the signer

shouldEnforceCustomDigitalCertificateValidation

boolean

required

Indicates if the custom digital certificate validation should be enforced for the signer

phoneIdd

integer <int32> | null

optional

Phone IDD of the signer, e.g. '1' for the United States or '55' for Brazil

phoneNumber

string | null

optional

Phone number of the signer excluding the IDD

documentType

enum<string> | enum<null>

optional

Type of the document to be used for the signer

Allowed values:

GenericIdentificationBrazilianCpf

documentValue

string | null

optional

Value of the document

shouldEnforcePasscodeValidation

boolean

required

Indicates if the passcode validation should be enforced for the signer

passcode

string | null

optional

Passcode of the signer

passcodeHint

string | null

optional

Passcode hint of the signer, which will be shown to the signer during the signing process

<= 200 characters

signMarks

array[object (CreateEnvelopeSignerSignMarkApiRequest) {6}] | null

optional

List of sign marks for the signer

documents

array[object (CreateEnvelopeDocumentApiRequest) {6}] | null

optional

List of documents

string <uuid>

required

Id of the document

>= 1 characters

name

string

required

Name of the document

>= 2 characters<= 200 characters

privateDescription

string | null

optional

Private description of the document

<= 4000 characters

publicDescription

string | null

optional

Public description of the document

<= 4000 characters

language

enum<string> | enum<null>

optional

Language of the document, if provided, it will override the language of the envelope

Allowed values:

EnUsPtBr

markupOrientation

enum<string> | enum<null>

optional

Markup orientation of the document, if provided, it will override the markup orientation of the envelope

Allowed values:

NoneBottomTopLeftRight

Example

{
  "vaultId": "0e8f52f8-5376-4526-a515-7de46409a7ed",
  "name": "Example Envelope",
  "privateDescription": "Private description of the envelope",
  "publicDescription": "Public description of the envelope",
  "message": "Message of the envelope",
  "reviewReminder": true,
  "expiresAtUtc": "2025-04-28T12:47:40.2764978Z",
  "expirationReminder": true,
  "toBePublishedAtUtc": "2025-03-30T12:47:40.2764983Z",
  "language": "EnUs",
  "markupOrientation": "Bottom",
  "signInOrder": true,
  "signers": [
    {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "role": "Sign",
      "title": "Lawyer",
      "shouldEnforceEmailValidation": true,
      "shouldEnforceSmsValidation": true,
      "shouldEnforceWhatsAppValidation": true,
      "shouldEnforcePixValidation": true,
      "shouldEnforceGeolocationValidation": true,
      "shouldAllowCustomDigitalCertificateValidation": true,
      "shouldEnforceCustomDigitalCertificateValidation": true,
      "phoneIdd": 1,
      "phoneNumber": "5555555555",
      "documentType": "GenericIdentification",
      "documentValue": "1234567890",
      "shouldEnforcePasscodeValidation": true,
      "passcode": "123456",
      "passcodeHint": "1 to 6",
      "signMarks": [
        {
          "type": "Rubric",
          "documentId": "5876c6ef-1427-4d60-98e1-583035280478",
          "page": 1,
          "x": 100,
          "y": 50,
          "rotation": 0
        },
        {
          "type": "Signature",
          "documentId": "5876c6ef-1427-4d60-98e1-583035280478",
          "page": 2,
          "x": 200,
          "y": 50,
          "rotation": 0
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "5876c6ef-1427-4d60-98e1-583035280478",
      "name": "Example Document",
      "privateDescription": "Private description of the document",
      "publicDescription": "Public description of the document",
      "language": "EnUs",
      "markupOrientation": "Bottom"
    }
  ]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.signater.com/v1/ecm/envelopes' \
--header 'Content-Type: application/json' \
--data-raw '{
    "vaultId": "0e8f52f8-5376-4526-a515-7de46409a7ed",
    "name": "Example Envelope",
    "privateDescription": "Private description of the envelope",
    "publicDescription": "Public description of the envelope",
    "message": "Message of the envelope",
    "reviewReminder": true,
    "expiresAtUtc": "2025-04-28T12:47:40.2764978Z",
    "expirationReminder": true,
    "toBePublishedAtUtc": "2025-03-30T12:47:40.2764983Z",
    "language": "EnUs",
    "markupOrientation": "Bottom",
    "signInOrder": true,
    "signers": [
        {
            "name": "John Doe",
            "email": "john.doe@example.com",
            "role": "Sign",
            "title": "Lawyer",
            "shouldEnforceEmailValidation": true,
            "shouldEnforceSmsValidation": true,
            "shouldEnforceWhatsAppValidation": true,
            "shouldEnforcePixValidation": true,
            "shouldEnforceGeolocationValidation": true,
            "shouldAllowCustomDigitalCertificateValidation": true,
            "shouldEnforceCustomDigitalCertificateValidation": true,
            "phoneIdd": 1,
            "phoneNumber": "5555555555",
            "documentType": "GenericIdentification",
            "documentValue": "1234567890",
            "shouldEnforcePasscodeValidation": true,
            "passcode": "123456",
            "passcodeHint": "1 to 6",
            "signMarks": [
                {
                    "type": "Rubric",
                    "documentId": "5876c6ef-1427-4d60-98e1-583035280478",
                    "page": 1,
                    "x": 100,
                    "y": 50,
                    "rotation": 0
                },
                {
                    "type": "Signature",
                    "documentId": "5876c6ef-1427-4d60-98e1-583035280478",
                    "page": 2,
                    "x": 200,
                    "y": 50,
                    "rotation": 0
                }
            ]
        }
    ],
    "documents": [
        {
            "id": "5876c6ef-1427-4d60-98e1-583035280478",
            "name": "Example Document",
            "privateDescription": "Private description of the document",
            "publicDescription": "Public description of the document",
            "language": "EnUs",
            "markupOrientation": "Bottom"
        }
    ]
}'

application/json

Envelope created successfully

Body

string <uuid>

optional

Id of the envelope

Example

{
  "id": "86da8bab-c17d-4bb0-b672-802d3c158be2"
}

Request

Request samples

Responses