---
title: "Create embedded invite"
url: "https://docs.signnow.com/docs/document-embedded-signing/operations/create-embedded-signing-invite"
type: "endpoint"
section: "document-embedded-signing"
slug: "document-embedded-signing/operations/create-embedded-signing-invite"
method: "POST"
path: "/v2/documents/{document_id}/embedded-invites"
operation_id: "create-embedded-signing-invite"
authorization: "bearer"
---
# Create embedded invite
`POST /v2/documents/{document_id}/embedded-invites`
This endpoint allows users to create an embedded signing invite for a document. Once the invite is created, generate an embedded signing link using [`POST v2/documents/{{document_id}}/embedded-invites/{{embedded_invite_id}}/link`](/docs/document-embedded-signing/operations/generate-link-for-embedded-invite) with the ID you got in the response.
Before sending your request, ensure the following:
- You are the owner of the document to be signed.
- The invite is being created for a document (not a template).
- Your document contains fields.
- The document is not part of any other invite (pending or signed).
- Signers' email addresses are unique and do not exceed 150 characters.
- All roles or role IDs in the document are included in the invite (specifying extra roles will result in an error).
- The document owner cannot be assigned as a signer.
You can also include `approvers`. These recipients review the document without signing or filling fields. Each approver requires `email`, `role`, `order`, and `auth_method`. Note that `order` values must be unique across `invites` and `approvers`.
Parameters `role` and `role_id` can be retrieved from the response from [`GET /document/{{document_id}}`](/docs/document/operations/get-document). Specify a role either by `role` (unique role name, e.g. “Signer 1”), `role_id` (unique role identifier), or both `role` and `role_id`. Ensure they correspond to each other.
Use these parameters to customize the request:
Recipient authentication for the signing session
Use the `authentication` object to set up the signer's authentication for the signing session.
* Authentication type: `phone`, method: `sms`. Note that `sms_message` parameter must contain `{password}` placeholder.
This method is used to authenticate the signer using a password sent via SMS.
```json
"authentication": {
"type": "phone",
"method": "sms",
"phone": "+1XXXXXXXXX",
"sms_message": "Custom test message with {password}"
}
```
* Authentication type: `phone`, method: `phone_call`
This method is used to authenticate the signer with a password delivered via a phone call.
```json
"authentication": {
"type": "phone",
"method": "phone_call",
"phone": "+1XXXXXXXXX"
}
```
* Authentication type: `password`
This method is used to authenticate the signer using a pre-set password.
```json
"authentication": {
"type": "password",
"password": "123456"
}
```
name_formula parameter
Use the `name_formula` parameter to generate a completed document name based on the `text_prefix` (can be any text) and fillable field data.
For example, let's set the first part of the completed document name as `Contract` and use data from two document fields (we can use up to five fields):
* `signer_name` (filled as `John Smith`)
* `signed_date` (filled as `20.01.2023`)
After the signer completes the document, the document will have the name `Contract John Smith 20.01.2023`.
Note that you can not use signature fields for `name_formula`.
auth_method used in the integrated application
The `auth_method` parameter is defined by the application owner to specify the method used to authenticate the signer within the integrated application.
Possible values are: `password`, `email`, `social`, `mfa`, `biometric`, `other`, `none`.
**Note**: The `auth_method` parameter does not influence the signer's authentication method during the signing session. Use the `authentication` object to configure authentication for the signing session.
from_email, from_name
Use `from_email` and `from_name` parameters to customize the appearance of the sender's email address and name.
Note that both parameters are optional and applicable only when `delivery_type`=`email`.
Explore the three scenarios of passing the from_name and from_email parameters:
**When both `from_email` and `from_name` are passed:**
The custom `from_name` appears:
- in email subject of the invite, reassign, reminder, and completed emails.
The custom `from_email` appears:
- in email body of the invite, reassign, reminder, and completed emails.
- when clicking **Contact Sender** and in **Reply-to** in the emails.
- in the signing session: when clicking **Contact Sender** in the **More Actions** menu.
---
**When only `from_email` is passed:**
The local part of `from_email` (before `@`) appears:
- in email subject of the invite, reassign, reminder, and completed emails.
The custom `from_email` appears:
- in email body of the invite, reassign, reminder, and completed emails.
- when clicking **Contact Sender** and in **Reply-to** in the emails.
- in the signing session: when clicking **Contact Sender** in the **More Actions** menu.
---
**When only `from_name` is passed:**
The custom `from_name` appears:
- in email subject of the invite, reassign, reminder, and completed emails.
The default (owner’s) `from_email` appears:
- in email body of the invite, reassign, reminder, and completed emails.
- when clicking **Contact Sender** and in **Reply-to** in the emails.
- in the signing session: when clicking **Contact Sender** in the **More Actions** menu.
Learn more about [embedded signing](/docs/guides-embedded-signing).
## Authorization
bearer
## Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | string | Yes | Document ID. |
## Request Body
**Schema**
```json
{
"type": "object",
"properties": {
"invites": {
"type": "array",
"items": {
"type": "object",
"required": [
"email",
"role_id",
"order",
"auth_method"
],
"properties": {
"role": {
"type": "string",
"example": "Recipient 1",
"description": "Recipient's role name."
},
"email": {
"type": "string",
"example": "signer@email.com",
"description": "Email address of the recipient."
},
"order": {
"type": "integer",
"example": 1,
"description": "The order of signing."
},
"message": {
"type": "string",
"example": "Please review the invoice and sign it at your earliest convenience.",
"maxLength": 5000,
"description": "Invite email message. Available if the `delivery_type` = `email`. Overrides branding settings when sending emails.",
"x-stoplight": {
"id": "p6qdwelzotcow"
}
},
"subject": {
"type": "string",
"example": "Review and sign the invoice",
"maxLength": 1000,
"description": "Invite email subject. Available if the `delivery_type` = `email`. Overrides branding settings when sending emails.",
"x-stoplight": {
"id": "hweqz6janu23i"
}
},
"language": {
"type": "string",
"example": "en",
"description": "Sets the language of the signing session for the recipient. Possible values: `en` for English, `es` for Spanish, `fr` for French."
},
"last_name": {
"type": "string",
"example": "Doe",
"description": "Signer's last name."
},
"signature": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "eideasy",
"description": "Type of the QES. Allowed vaules are `eideasy`, `nom151`. For more information, see [QES user guide](/docs/qualified-electronic-signature).",
"x-stoplight": {
"id": "chg74gqg704ir"
}
}
},
"description": "This object is used to request QES signatures from signers. To create an embedded invite with QES, a user must be a member of an organization with QES settings enabled. If QES is specified, it must be used for all signers in the invite.",
"x-stoplight": {
"id": "i44p23xv82csv"
}
},
"first_name": {
"type": "string",
"example": "John",
"description": "Signer's first name."
},
"auth_method": {
"type": "string",
"example": "none",
"description": "Defines the method used to authenticate the recipient within the integrated application. Allowed values: `password`, `email`, `mfa`, `biometric`, `social`, `other`, `none`."
},
"redirect_uri": {
"type": "string",
"example": "https://example.com",
"description": "The link that opens after the signing session has been completed."
},
"authentication": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "phone",
"description": "Authentication type used for the recipient authentication during the signing session. Required inside `authentication` object. Allowed values: `phone`, `password`."
},
"phone": {
"type": "string",
"example": "+1XXXXXXXXX",
"description": "Phone number used to authenticate the recipient. Required inside `authentication` object with the `phone` method."
},
"method": {
"type": "string",
"example": "sms",
"description": "Method of the `phone` authentication type. Required inside `authentication` object with the `phone` authentication type. Allowed values: `sms`, `phone_call`.\n"
},
"password": {
"type": "string",
"example": "123456",
"description": "Password set for the recipient authentication. Required inside the `authentication` object with the `password` authentication type."
},
"sms_message": {
"type": "string",
"example": "Enter the password {password} to unlock your document.",
"maxLength": 140,
"description": "Custom sms message sent to the recipient, containing the {password} placeholder. Used with the `sms` method. Without this parameter, the recipient receives a default sms with an autogenerated password (unlock code) - \"SignNow document invite unlock code: 123456\"."
}
},
"description": "Authentication settings used to verify the recipient identity."
},
"delivery_type ": {
"type": "string",
"default": "link",
"description": "Defines how the invite is sent. Allowed values: `email`, `link`.\n"
},
"redirect_target": {
"type": "string",
"default": "self",
"description": "Determines whether to open the redirect link in the new tab in the browser, or in the same tab after the signing session. Possible values: `blank` - opens the link in the new tab, `self` - opens the link in the same tab."
},
"link_expiration ": {
"type": "integer",
"maximum": 43200,
"minimum": 15,
"description": "In how many minutes the email invite expires. Can be used only if `delivery_type`=`email`."
},
"close_redirect_uri": {
"type": "string",
"example": "https://example.com",
"description": "The link that opens when a signer clicks **Save Progress and Finish Later** during a signing session or **Close** in view mode."
},
"session_expiration": {
"type": "integer",
"maximum": 1440,
"minimum": 15,
"description": "In how many minutes the signing session expires. If a link is generated for this invite, the session expiration is reset. Can be used only if `delivery_type=email`.",
"x-stoplight": {
"id": "2xz1y3kaq2nha"
}
},
"force_new_signature": {
"type": "integer",
"example": 0,
"description": "Defines whether the signer can use their saved signature or not. If set to `1`, the signer has to add a new signature. If set to `0`, the signer can use the saved signature.\n"
},
"decline_redirect_uri": {
"type": "string",
"example": "https://example.com",
"description": "The link that opens after the signing session has been declined by the signer."
},
"prefill_signature_name": {
"type": "string",
"example": "John Doe",
"maxLength": 255,
"description": "The text displayed in the Signature field. The signer can edit this value."
},
"required_preset_signature_name": {
"type": "string",
"example": "Jane Smith",
"description": "The text displayed in the Signature field. The signer cannot edit this value. Can not be used simultaneously with `prefill_signature_name` or `force_new_signature` for the same role."
}
}
},
"description": "The object that holds the attributes of the invite."
},
"approvers": {
"type": "array",
"items": {
"type": "object",
"required": [
"email",
"role",
"order",
"auth_method"
],
"properties": {
"role": {
"type": "string",
"example": "Approver 1",
"maxLength": 255,
"description": "Approver's role name. Must be unique within `approvers`."
},
"email": {
"type": "string",
"example": "approver@email.com",
"description": "Email address of the approver."
},
"order": {
"type": "integer",
"example": 2,
"maximum": 127,
"minimum": 1,
"description": "The order of approval. Each `order` value in `approvers` must be unique within the array and must not be shared with signer roles."
},
"message": {
"type": "string",
"example": "Please review the invoice and approve it at your earliest convenience.",
"maxLength": 5000,
"description": "Invite email message. Available if the `delivery_type` = `email`. Overrides branding settings when sending emails."
},
"subject": {
"type": "string",
"example": "Review and approve the invoice",
"maxLength": 1000,
"description": "Invite email subject. Available if the `delivery_type` = `email`. Overrides branding settings when sending emails."
},
"language": {
"type": "string",
"example": "en",
"description": "Sets the language of the approval session for the approver. Possible values: `en` for English, `es` for Spanish, `fr` for French."
},
"last_name": {
"type": "string",
"example": "Doe",
"description": "Approver's last name."
},
"first_name": {
"type": "string",
"example": "John",
"description": "Approver's first name."
},
"auth_method": {
"type": "string",
"example": "none",
"description": "Defines the method used to authenticate the approver within the integrated application. Allowed values: `password`, `email`, `mfa`, `biometric`, `social`, `other`, `none`."
},
"delivery_type": {
"type": "string",
"default": "link",
"description": "Defines how the invite is sent. Allowed values: `email`, `link`."
},
"authentication": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "phone",
"description": "Authentication type used for the approver authentication during the approval session. Required inside `authentication` object. Allowed values: `phone`, `password`."
},
"phone": {
"type": "string",
"example": "+1XXXXXXXXX",
"description": "Phone number used to authenticate the approver. Required inside `authentication` object with the `phone` method."
},
"method": {
"type": "string",
"example": "sms",
"description": "Method of the `phone` authentication type. Required inside `authentication` object with the `phone` authentication type. Allowed values: `sms`, `phone_call`."
},
"password": {
"type": "string",
"example": "123456",
"description": "Password set for the approver authentication. Required inside the `authentication` object with the `password` authentication type."
},
"sms_message": {
"type": "string",
"example": "Enter the password {password} to unlock your document.",
"maxLength": 140,
"description": "Custom SMS message sent to the approver, containing the {password} placeholder. Used with the `sms` method."
}
},
"description": "Authentication settings used to verify the approver identity."
},
"link_expiration": {
"type": "integer",
"maximum": 43200,
"minimum": 15,
"description": "In how many minutes the email invite expires. Can be used only if `delivery_type`=`email`."
},
"session_expiration": {
"type": "integer",
"maximum": 1440,
"minimum": 15,
"description": "In how many minutes the approval session expires. If a link is generated for this invite, the session expiration is reset. Can be used only if `delivery_type=email`."
}
}
},
"description": "The object that holds the attributes of the approver. Approvers review the document but do not sign or fill in fields. `order` values must be unique across `invites` and `approvers`."
},
"from_name": {
"type": "string",
"example": "Jane Doe",
"maxLength": 300,
"description": "Use this attribute to customize the name that appears in email subject of the invite, reassign, reminder, and completed emails. Note: applicable when `delivery_type`=`email`."
},
"from_email": {
"type": "string",
"example": "sender@email.com",
"maxLength": 255,
"description": "Use this attribute to customize the email address that appears: 1) in the invite, reassign, reminder, and completed emails: in email subject (part before @) and email body; when clicking Contact Sender, and in Reply-to; 2) in the signing session: when clicking the Contact Sender button in the More Actions menu. Note: applicable when `delivery_type`=`email`."
},
"name_formula": {
"type": "string",
"example": "Contract|signer_name|signed_date",
"description": "Used to generate a completed document name based on `text_prefix` (can be any text) and field data (excluding signature fields). You can use up to 5 fields."
}
},
"x-examples": {
"Example 1": {
"invites": [
{
"role": "Recipient 1",
"email": "signer1@email.com",
"order": 1,
"language": "en",
"last_name": "Smith",
"first_name": "John",
"auth_method": "none",
"redirect_uri": "https://example.com/redirect",
"authentication": {
"type": "password",
"password": "password"
},
"prefill_signature_name": "Recipient signature"
},
{
"role": "Recipient 2",
"email": "signer2@email.com",
"order": 1,
"language": "en",
"last_name": "Johnson",
"first_name": "Emily",
"auth_method": "biometric",
"authentication": {
"type": "phone",
"phone": "+1111111111",
"method": "phone_call"
}
},
{
"role": "Recipient 3",
"email": "signer3@email.com",
"order": 2,
"language": "en",
"last_name": "Brown",
"first_name": "Michael",
"auth_method": "password",
"authentication": {
"type": "phone",
"phone": "+1111111111",
"method": "sms",
"sms_message": "Your custom test message with {password}"
}
}
],
"approvers": [
{
"role": "Approver 1",
"email": "approver1@email.com",
"order": 3,
"message": "Review and approve the document.",
"subject": "Please approve the document",
"language": "en",
"last_name": "Williams",
"first_name": "Sarah",
"auth_method": "none",
"delivery_type": "email",
"authentication": {
"type": "phone",
"phone": "+1111111111",
"method": "phone_call"
},
"link_expiration": 15,
"session_expiration": 15
}
],
"name_formula": "some text|field1_name|field2_name|field3_name|field4_name|field5_name"
}
}
}
```
**Example** (`Example 1`)
```json
{
"invites": [
{
"role": "Signer 1",
"email": "signer1@email.com",
"order": 1,
"language": "en",
"last_name": "Doe",
"signature": {
"type": "eideasy"
},
"first_name": "John",
"auth_method": "email",
"redirect_uri": "https://example.com",
"authentication": {
"type": "password",
"password": "12345"
},
"redirect_target": "blank",
"close_redirect_uri": "https://example.com/",
"decline_redirect_uri": "https://signnow.com",
"required_preset_signature_name": "Signer signature"
},
{
"role": "Signer 2",
"email": "signer2@email.com",
"order": 2,
"message": "Please review the invoice and sign it at your earliest convenience.",
"subject": "Sign the invoice",
"language": "en",
"signature": {
"type": "eideasy"
},
"auth_method": "email",
"delivery_type": "email",
"authentication": {
"type": "phone",
"phone": "+1234567890",
"method": "sms",
"sms_message": "Enter the password {password} to unlock your document."
},
"link_expiration": 15,
"session_expiration": 15,
"prefill_signature_name": "Recipient signature"
},
{
"role": "Signer 3",
"email": "signer3@email.com",
"order": 3,
"language": "en",
"signature": {
"type": "eideasy"
},
"auth_method": "email",
"delivery_type": "link",
"authentication": {
"type": "phone",
"phone": "+0987654321",
"method": "phone_call"
},
"force_new_signature": 0
}
],
"approvers": [
{
"role": "Approver 1",
"email": "approver1@email.com",
"order": 4,
"message": "Review and approve the contract at your earliest convenience.",
"subject": "Please approve the contract",
"language": "en",
"last_name": "Roe",
"first_name": "Alex",
"auth_method": "email",
"delivery_type": "email",
"authentication": {
"type": "password",
"password": "12345"
},
"link_expiration": 15,
"session_expiration": 15
},
{
"role": "Approver 2",
"email": "approver2@email.com",
"order": 5,
"language": "es",
"last_name": "Lee",
"first_name": "Jamie",
"auth_method": "email",
"delivery_type": "link",
"authentication": {
"type": "phone",
"phone": "+1234567890",
"method": "sms",
"sms_message": "Enter the password {password} to unlock your document."
}
}
],
"from_name": "Jane Doe",
"from_email": "sender@email.com",
"name_formula": "Contract|signer_name|signed_date"
}
```
## Responses
### 201
* Response to a correct request
* Response to a correct request with `name_formula` parameter to change the completed document name.
**Example** (`application/json`)
```json
{
"data": [
{
"id": "03XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"email": "signer1@email.com",
"order": 1,
"status": "pending",
"role_id": "33XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
{
"id": "b9XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"email": "signer2@email.com",
"order": 1,
"status": "pending",
"role_id": "88XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
{
"id": "c7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"email": "signer3@email.com",
"order": 1,
"status": "pending",
"role_id": "99XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
{
"id": "a4XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"email": "approver1@email.com",
"order": 4,
"status": "created",
"role_id": "44XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
{
"id": "a5XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"email": "approver2@email.com",
"order": 5,
"status": "created",
"role_id": "55XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
]
}
```
**Example** (`Response to a correct request`)
```json
{
"data": [
{
"id": "13XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"link": "https://example.com",
"email": "signer@email.com",
"order": 1,
"status": "pending",
"role_id": "c8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"expires_at": 1589546224,
"redirect_uri": "https://example.com",
"redirect_target": "blank",
"decline_redirect_uri": "https://signnow.com"
},
{
"id": "a7XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"email": "approver@email.com",
"order": 2,
"status": "created",
"role_id": "44XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
]
}
```
**Example** (`With "name_formula" parameter `)
```json
{
"data": [
{
"id": "5fXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"email": "signer@email.com",
"order": 1,
"status": "pending",
"role_id": "58XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
]
}
```
### 400
* Document has active invites.
* Email addresses in embedded invites are not unique.
* Document has no active fields.
* The role doesn't exist in the document.
* Document owner's email was used as a signer's email.
* Not all of the document roles were used.
* Invite for the role already exists.
**Validation errors**:
* The `prefill_signature_name` contains unsupported characters.
* The `authentication.type` is not a string.
* The `authentication.type` is not valid. Possible values: `phone`, `password`.
* The `phone` is not a string.
* The `phone` format is not valid.
* The `phone` field is required when `authentication.type` = `phone`.
* The `method` is not valid. Possible values: `sms`, `phone_call`.
* The`method` parameter can be used if `authentication.type` = `phone`.
* The `password` is not a string.
* The `password` parameter is required when `authentication.type` = `password`.
* The `sms_message` is not a string.
* The `sms_message` value is empty.
* The `sms_message` value is too long (must have 154 characters or less).
* The `sms_message` contains unsupported characters.
* The `phone` parameter is required when `authentication.type` = `phone`.
* The `method` parameter is required when `authentication.type` = `phone`.
* The `sms_message` parameter can be used only when `authentication.type` = `phone` and `method` = `sms`.
* The `password` field is required when `authentication.type` = `password`.
* The `method` field is not a string.
* The `authentication.type` is empty.
* The `name_formula` field is not a string.
* The `name_formula` value is empty.
* The `name_formula` contains unsupported characters.
* The `name_formula` contains more than 5 fields.
* The `name_formula` have `{field_name}` that does not exist in document or field type is not text.
* The `name_formula` have duplicate `{field_name}` values.
* The `required_preset_signature_name` is not a string.
* The `required_preset_signature_name` value is empty.
* The `required_preset_signature_name` is too long (must not exceed 255 characters).
* The `required_preset_signature_name` contains unsupported characters.
* Parameter `required_preset_signature_name` is used with `prefill_signature_name` for the same role.
* Parameter `required_preset_signature_name` is used with `force_new_signature` for the same role.
* The `language` is not a string.
* The`language` is incorrect. Possible values: `en`, `fr`, `es`.
* The `decline_redirect_uri` is not a string.
* The `decline_redirect_uri` is empty.
* The`decline_redirect_uri` is not a correct URL.
* The`redirect_target` is not a string.
* The`redirect_target` is incorrect. Possible values: self, blank.
* One of `redirect_uri` fields is required when `redirect_target` is added.
* The `redirect_uri` is too long (must not exceed 2048 characters).
* The `decline_redirect_uri` is too long (must not exceed 2048 characters).
* The `delivery_type` is not a string.
* Incorrect `delivery_type`. Possible values: `email`, `link`.
* The `link_expiration` is not an integer.
* The `link_expiration` is incorrect (must be 15 or more).
* The `link_expiration` is incorrect (must be 45 or less).
* The `link_expiration` can only be used if `delivery_type=email`.
* The `session_expiration` is not an integer.
* The `session_expiration` is out of range.
* The `session_expiration` can only be used if `delivery_type=email`.
* Parameter `subject` in `invites` is not a string.
* Parameter `subject` in `invites` is empty.
* Parameter `subject` in `invites` contains unsupported characters.
* Parameter `subject` in `invites` is too long.
* Parameter `subject` in `invites` is used when `delivery_type` is not `email`.
* Parameter `message` in `invites` is not a string.
* Parameter `message` in `invites` is empty.
* Parameter `message` in `invites` contains unsupported characters.
* Parameter `message` in `invites` is too long.
* Parameter `message` in `invites` is used when `delivery_type` is not `email`.
* Your subscription plan does not include email invite customization.
**QES-specific errors**:
* The organization has no advanced sign provider enabled.
* The user is not part of the organization.
* Multiple signers were found in a single step.
* Different signature providers assigned to signers.
* The `signature` field type is incorrect.
* The `signature.type` value is empty.
* The `signature.type` value type is incorrect.
* The `signature.type` value is not supported.
**Approver-specific errors**:
* The `approvers` field is not an array.
* The `approvers` field items are not arrays.
* In `approvers`, multiple approvers share the same `order`.
* An approver's `order` is shared with another role.
* In `approvers`, role names are not unique.
* The `email` field in `approvers` is not a string / is blank / is not a valid email.
* The `role` field in `approvers` is not a string / is blank / exceeds 255 characters / contains 4-byte characters.
* The `order` field in `approvers` is not an integer / is blank / is not between 1 and 127.
* The `auth_method` field in `approvers` is not a string / is blank / is not one of the allowed values.
* The `first_name` field in `approvers` is not a string / contains 4-byte characters / exceeds the character limit.
* The `last_name` field in `approvers` is not a string / contains 4-byte characters / exceeds the character limit.
* The `language` field in `approvers` is not a string / is invalid (allowed: `en`, `fr`, `es`).
* The `delivery_type` field in `approvers` is not a string / is invalid (allowed: `email`, `link`).
* The `link_expiration` field in `approvers` is not an integer / is less than 15 minutes / is set when `delivery_type` is not `email`.
* The `session_expiration` field in `approvers` is not an integer / is out of range / is set when `delivery_type` is not `email`.
* The `subject` field in `approvers` is not a string / is blank / contains 4-byte characters / exceeds the character limit / is set when `delivery_type` is not `email`.
* The `message` field in `approvers` is not a string / is blank / contains 4-byte characters / exceeds the character limit / is set when `delivery_type` is not `email`.
**Example** (`Example 1`)
```json
{
"errors": [
{
"code": "19003095",
"message": "The `signature.type` attribute is not valid. Allowed values: \u201ceideasy\u201d, \u201cnom151."
}
]
}
```
**Example** (`Unused role`)
```json
{
"errors": [
{
"code": 19002019,
"message": "Role {role_id} was not specified in any invite. All roles must be used."
}
]
}
```
**Example** (`Message is empty`)
```json
{
"errors": [
{
"code": 19003106,
"message": "The `message` field in `invites` must not be an empty string."
}
]
}
```
**Example** (`More than 1 step`)
```json
{
"errors": [
{
"code": 19002004,
"message": "Can send an embedded invite with only one step."
}
]
}
```
**Example** (`No active fields`)
```json
{
"errors": [
{
"code": 19002016,
"message": "Cannot send an invite. This document does not contain fields."
}
]
}
```
**Example** (`Subject is empty`)
```json
{
"errors": [
{
"code": 19003101,
"message": "The `subject` field in `invites` must not be an empty string."
}
]
}
```
**Example** (`Duplicated emails`)
```json
{
"errors": [
{
"code": 19002005,
"message": "Emails in embedded invites must be unique."
}
]
}
```
**Example** (`Non-existent role`)
```json
{
"errors": [
{
"code": 19002018,
"message": "Role {role_id} does not exist in the document."
}
]
}
```
**Example** (`Owner is a signer`)
```json
{
"errors": [
{
"code": 19002021,
"message": "The document owner cannot send invite to himself."
}
]
}
```
**Example** (`Approver role blank`)
```json
{
"errors": [
{
"code": 19003123,
"message": "The `role` field in `approvers` must not be blank."
}
]
}
```
**Example** (`Different providers`)
```json
{
"errors": [
{
"code": 19003096,
"message": "The `signature.type` fields must be the same for all signers."
}
]
}
```
**Example** (`Message is too long`)
```json
{
"errors": [
{
"code": 19003108,
"message": "The `message` field in `invites` must not exceed 5000 characters."
}
]
}
```
**Example** (`Subject is too long`)
```json
{
"errors": [
{
"code": 19003103,
"message": "The `subject` field in `invites` must not exceed 1000 characters."
}
]
}
```
**Example** (`Approver email blank`)
```json
{
"errors": [
{
"code": 19003120,
"message": "The `email` field in `approvers` must not be blank."
}
]
}
```
**Example** (`Approver order blank`)
```json
{
"errors": [
{
"code": 19003127,
"message": "The `order` field in `approvers` must not be blank."
}
]
}
```
**Example** (`Authentication errors`)
```json
{
"invites": [
{
"email": "signer1@email.com",
"order": 1,
"role_id": "role_id",
"last_name": "qwerty",
"first_name": "qwerty",
"auth_method": "email",
"authentication": {
"type": "phone",
"phone": "+1XXX-XXXXXXX",
"method": "sms",
"sms_message": "message"
}
},
{
"email": "signer2@email.com",
"order": 1,
"role_id": "role_id",
"last_name": "qwerty",
"first_name": "qwerty",
"auth_method": "email",
"authentication": {
"type": "password",
"password": "password"
}
}
]
}
```
**Example** (`Message is not string`)
```json
{
"errors": [
{
"code": 19003105,
"message": "The `message` field in `invites` must be a string."
}
]
}
```
**Example** (`Subject is not string`)
```json
{
"errors": [
{
"code": 19003100,
"message": "The `subject` field in `invites` must be a string."
}
]
}
```
**Example** (`Approver email invalid`)
```json
{
"errors": [
{
"code": 19003121,
"message": "The `email` field in `approvers` must be a valid email."
}
]
}
```
**Example** (`Approver message empty`)
```json
{
"errors": [
{
"code": 19003157,
"message": "The `message` field in `approvers` must not be an empty string."
}
]
}
```
**Example** (`Approver role too long`)
```json
{
"errors": [
{
"code": 19003124,
"message": "The `role` field in `approvers` must contain no more than 255 characters."
}
]
}
```
**Example** (`Approver subject empty`)
```json
{
"errors": [
{
"code": 19003152,
"message": "The `subject` field in `approvers` must not be an empty string."
}
]
}
```
**Example** (`approvers is not array`)
```json
{
"errors": [
{
"code": 19003117,
"message": "The `approvers` field must be an array."
}
]
}
```
**Example** (`Incorrect delivery_type`)
```json
{
"errors": [
{
"code": 19003083,
"message": "The `delivery_type field` in `invites` is invalid, allowed values: email, link."
}
]
}
```
**Example** (`link_expiration too big`)
```json
{
"errors": [
{
"code": 19004009,
"message": "The `link_expiration` field in `invites` must be less than or equal to 45 minutes."
}
]
}
```
**Example** (`signature.type is empty`)
```json
{
"errors": [
{
"code": 19003094,
"message": "The `signature.type` cannot be null."
}
]
}
```
**Example** (`Approver role not string`)
```json
{
"errors": [
{
"code": 19003122,
"message": "The `role` field in `approvers` must be a string."
}
]
}
```
**Example** (`Approver role not unique`)
```json
{
"errors": [
{
"code": 19003134,
"message": "In the `approvers` field, each role name must be unique."
}
]
}
```
**Example** (`User not in organization`)
```json
{
"errors": [
{
"code": 19004011,
"message": "Organization is required to send an invite with advanced signing."
}
]
}
```
**Example** (`delivery_type not string`)
```json
{
"errors": [
{
"code": 19003082,
"message": "The `delivery_type` field in `invites` must be a string."
}
]
}
```
**Example** (`Approver email not string`)
```json
{
"errors": [
{
"code": 19003119,
"message": "The `email` field in `approvers` must be a string."
}
]
}
```
**Example** (`Approver language invalid`)
```json
{
"errors": [
{
"code": 19003142,
"message": "The `language` field in `approvers` is invalid. Allowed values: en, fr, es."
}
]
}
```
**Example** (`Approver message too long`)
```json
{
"errors": [
{
"code": 19003159,
"message": "The `message` field in `approvers` must not exceed 5000 characters."
}
]
}
```
**Example** (`Approver subject too long`)
```json
{
"errors": [
{
"code": 19003154,
"message": "The `subject` field in `approvers` must not exceed 1000 characters."
}
]
}
```
**Example** (`No advanced sign provider`)
```json
{
"errors": [
{
"code": 19004012,
"message": "The sender organization\u2019s advanced sign provider is not valid."
}
]
}
```
**Example** (`Redundant link_expiration`)
```json
{
"errors": [
{
"code": 19003086,
"message": "In `invites`, the `link_expiration` field must be used if the `delivery_type` field contains `email`."
}
]
}
```
**Example** (`approvers items not array`)
```json
{
"errors": [
{
"code": 19003118,
"message": "The `approvers` field items must be arrays."
}
]
}
```
**Example** (`Approver auth_method blank`)
```json
{
"errors": [
{
"code": 19003130,
"message": "The `auth_method` field in `approvers` must not be blank."
}
]
}
```
**Example** (`Approver order not integer`)
```json
{
"errors": [
{
"code": 19003126,
"message": "The `order` field in `approvers` must be an integer."
}
]
}
```
**Example** (`link_expiration too little`)
```json
{
"errors": [
{
"code": 19003085,
"message": "The `link_expiration` field in `invites` must be greater than or equal to 15 minutes."
}
]
}
```
**Example** (`Approver last_name too long`)
```json
{
"errors": [
{
"code": 19003140,
"message": "The `last_name` field in `approvers` must not exceed 64 characters."
}
]
}
```
**Example** (`Approver message not string`)
```json
{
"errors": [
{
"code": 19003156,
"message": "The `message` field in `approvers` must be a string."
}
]
}
```
**Example** (`Approver order out of range`)
```json
{
"errors": [
{
"code": 19003128,
"message": "The `order` field in `approvers` must be between 1 and 127."
}
]
}
```
**Example** (`Approver subject not string`)
```json
{
"errors": [
{
"code": 19003151,
"message": "The `subject` field in `approvers` must be a string."
}
]
}
```
**Example** (`Document has active invites`)
```json
{
"errors": [
{
"code": 19002017,
"message": "An invite already exists for this document."
}
]
}
```
**Example** (`Signature type is incorrect`)
```json
{
"errors": [
{
"code": 19003099,
"message": "The `signature` field in `invites` must be an array."
}
]
}
```
**Example** (`link_expiration not integer`)
```json
{
"errors": [
{
"code": 19003084,
"message": "The `link_expiration` field in `invites` must be an integer."
}
]
}
```
**Example** (`signature.type is incorrect`)
```json
{
"errors": [
{
"code": 19003098,
"message": "The `signature.type` must be a string."
}
]
}
```
**Example** (`Approver auth_method invalid`)
```json
{
"errors": [
{
"code": 19003131,
"message": "The `auth_method` field in `approvers` must be one of the allowed values."
}
]
}
```
**Example** (`Approver first_name too long`)
```json
{
"errors": [
{
"code": 19003137,
"message": "The `first_name` field in `approvers` must not exceed 64 characters."
}
]
}
```
**Example** (`Approver language not string`)
```json
{
"errors": [
{
"code": 19003141,
"message": "The `language` field in `approvers` must be a string."
}
]
}
```
**Example** (`Redundant session_expiration`)
```json
{
"errors": [
{
"code": 19003093,
"message": "In `invites`, the `session_expiration` field must be used if the `delivery_type` field contains `email`."
}
]
}
```
**Example** (`Approver last_name not string`)
```json
{
"errors": [
{
"code": 19003138,
"message": "The `last_name` field in `approvers` must be a string."
}
]
}
```
**Example** (`Approver message 4-byte chars`)
```json
{
"errors": [
{
"code": 19003158,
"message": "UTF-8 4-byte characters in the `message` field in `approvers` are not supported."
}
]
}
```
**Example** (`Approver subject 4-byte chars`)
```json
{
"errors": [
{
"code": 19003153,
"message": "UTF-8 4-byte characters in the `subject` field in `approvers` are not supported."
}
]
}
```
**Example** (`Multiple signers for one step`)
```json
{
"errors": [
{
"code": 19003097,
"message": "Must have only one signer per step if a signature field exists."
}
]
}
```
**Example** (`Approver delivery_type invalid`)
```json
{
"errors": [
{
"code": 19003144,
"message": "The `delivery_type` field in `approvers` is invalid. Allowed values: email, link."
}
]
}
```
**Example** (`Approver first_name not string`)
```json
{
"errors": [
{
"code": 19003135,
"message": "The `first_name` field in `approvers` must be a string."
}
]
}
```
**Example** (`session_expiration not integer`)
```json
{
"errors": [
{
"code": 19003091,
"message": "The `session_expiration` field in `invites` must be an integer."
}
]
}
```
**Example** (`Approver auth_method not string`)
```json
{
"errors": [
{
"code": 19003129,
"message": "The `auth_method` field in `approvers` must be a string."
}
]
}
```
**Example** (`Approver last_name 4-byte chars`)
```json
{
"errors": [
{
"code": 19003139,
"message": "UTF-8 4-byte characters in the `last_name` field in `approvers` are not supported."
}
]
}
```
**Example** (`session_expiration out of range`)
```json
{
"errors": [
{
"code": 19003092,
"message": "The `session_expiration` field in `invites` must be between 15 and 1440 minutes."
}
]
}
```
**Example** (`signature.type is not supported`)
```json
{
"errors": [
{
"code": 19003095,
"message": "The `signature.type` attribute is not valid. Allowed values: \u201ceideasy\u201d, \u201cnom151."
}
]
}
```
**Example** (`Approver first_name 4-byte chars`)
```json
{
"errors": [
{
"code": 19003136,
"message": "UTF-8 4-byte characters in the `first_name` field in `approvers` are not supported."
}
]
}
```
**Example** (`Approver delivery_type not string`)
```json
{
"errors": [
{
"code": 19003143,
"message": "The `delivery_type` field in `approvers` must be a string."
}
]
}
```
**Example** (`Email customization not available`)
```json
{
"errors": [
{
"code": 19004014,
"message": "Upgrade your subscription plan to customize the invite subject and message."
}
]
}
```
**Example** (`Approver link_expiration too small`)
```json
{
"errors": [
{
"code": 19003146,
"message": "The `link_expiration` field in `approvers` must be greater than or equal to 15 minutes."
}
]
}
```
**Example** (`Approver link_expiration not integer`)
```json
{
"errors": [
{
"code": 19003145,
"message": "The `link_expiration` field in `approvers` must be an integer."
}
]
}
```
**Example** (`Approver order shared with another role`)
```json
{
"errors": [
{
"code": 19003133,
"message": "An approver's `order` must not be shared with other roles."
}
]
}
```
**Example** (`Approver session_expiration not integer`)
```json
{
"errors": [
{
"code": 19003148,
"message": "The `session_expiration` field in `approvers` must be an integer."
}
]
}
```
**Example** (`Message contains unsupported characters`)
```json
{
"errors": [
{
"code": 19003107,
"message": "UTF-8 4-byte characters in the `message` field are not supported."
}
]
}
```
**Example** (`Subject contains unsupported characters`)
```json
{
"errors": [
{
"code": 19003102,
"message": "UTF-8 4-byte characters in the `subject` field are not supported."
}
]
}
```
**Example** (`Approver order conflict within approvers`)
```json
{
"errors": [
{
"code": 19003132,
"message": "In the `approvers` field, each `order` must have only one approver."
}
]
}
```
**Example** (`Approver role contains 4-byte characters`)
```json
{
"errors": [
{
"code": 19003125,
"message": "The `role` field in `approvers` must not contain 4-byte characters."
}
]
}
```
**Example** (`Approver session_expiration out of range`)
```json
{
"errors": [
{
"code": 19003149,
"message": "The `session_expiration` field in `approvers` must be between 15 and 1440 minutes."
}
]
}
```
**Example** (`Message is used with wrong delivery_type`)
```json
{
"errors": [
{
"code": 19003109,
"message": "The `message` field in `invites` must be used only if the `delivery_type` field is set to `email`."
}
]
}
```
**Example** (`Subject is used with wrong delivery_type`)
```json
{
"errors": [
{
"code": 19003104,
"message": "The `subject` field in `invites` must be used only if the `delivery_type` field is set to `email`."
}
]
}
```
**Example** (`Approver message with wrong delivery_type`)
```json
{
"errors": [
{
"code": 19003160,
"message": "The `message` field in `approvers` must be used only if the `delivery_type` field is set to `email`."
}
]
}
```
**Example** (`Approver subject with wrong delivery_type`)
```json
{
"errors": [
{
"code": 19003155,
"message": "The `subject` field in `approvers` must be used only if the `delivery_type` field is set to `email`."
}
]
}
```
**Example** (`Approver link_expiration with wrong delivery_type`)
```json
{
"errors": [
{
"code": 19003147,
"message": "The `link_expiration` field in `approvers` must be used only if the `delivery_type` field is set to `email`."
}
]
}
```
**Example** (`Approver session_expiration with wrong delivery_type`)
```json
{
"errors": [
{
"code": 19003150,
"message": "The `session_expiration` field in `approvers` must be used only if the `delivery_type` field is set to `email`."
}
]
}
```
### 403
User doesn't own the document
**Example** (`Example 1`)
```json
{
"errors": [
{
"code": 19001002,
"message": "User is not document owner."
}
]
}
```
**Example** (`User doesn't own the document`)
```json
{
"code": 19001002,
"message": "User is not document owner."
}
```
### 404
Document not found
**Example** (`Document not found`)
```json
{
"errors": [
{
"code": 19002001,
"message": "Document not found"
}
]
}
```
### 422
Document is template
**Example** (`Document is template`)
```json
{
"errors": [
{
"code": 19001003,
"message": "Cannot send invites for templates."
}
]
}
```
## Code Examples
> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.
### cURL
```bash
curl -X POST \
"https://api.signnow.com/v2/documents/{document_id}/embedded-invites" \
-H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"invites": [{"role": "Signer 1", "email": "signer1@email.com", "order": 1, "language": "en", "last_name": "Doe", "signature": {"type": "eideasy"}, "first_name": "John", "auth_method": "email", "redirect_uri": "https://example.com", "authentication": {"type": "password", "password": "12345"}, "redirect_target": "blank", "close_redirect_uri": "https://example.com/", "decline_redirect_uri": "https://signnow.com", "required_preset_signature_name": "Signer signature"}, {"role": "Signer 2", "email": "signer2@email.com", "order": 2, "message": "Please review the invoice and sign it at your earliest convenience.", "subject": "Sign the invoice", "language": "en", "signature": {"type": "eideasy"}, "auth_method": "email", "delivery_type": "email", "authentication": {"type": "phone", "phone": "+1234567890", "method": "sms", "sms_message": "Enter the password {password} to unlock your document."}, "link_expiration": 15, "session_expiration": 15, "prefill_signature_name": "Recipient signature"}, {"role": "Signer 3", "email": "signer3@email.com", "order": 3, "language": "en", "signature": {"type": "eideasy"}, "auth_method": "email", "delivery_type": "link", "authentication": {"type": "phone", "phone": "+0987654321", "method": "phone_call"}, "force_new_signature": 0}], "approvers": [{"role": "Approver 1", "email": "approver1@email.com", "order": 4, "message": "Review and approve the contract at your earliest convenience.", "subject": "Please approve the contract", "language": "en", "last_name": "Roe", "first_name": "Alex", "auth_method": "email", "delivery_type": "email", "authentication": {"type": "password", "password": "12345"}, "link_expiration": 15, "session_expiration": 15}, {"role": "Approver 2", "email": "approver2@email.com", "order": 5, "language": "es", "last_name": "Lee", "first_name": "Jamie", "auth_method": "email", "delivery_type": "link", "authentication": {"type": "phone", "phone": "+1234567890", "method": "sms", "sms_message": "Enter the password {password} to unlock your document."}}], "from_name": "Jane Doe", "from_email": "sender@email.com", "name_formula": "Contract|signer_name|signed_date"}'
```
---
*Full reference: https://docs.signnow.com/docs/document-embedded-signing/operations/create-embedded-signing-invite*