---
title: "Create embedded invite"
url: "https://docs.signnow.com/docs/doc-group-embedded-signing/operations/create-embedded-invite-document-group"
type: "endpoint"
section: "doc-group-embedded-signing"
slug: "doc-group-embedded-signing/operations/create-embedded-invite-document-group"
method: "POST"
path: "/v2/document-groups/{document_group_id}/embedded-invites"
operation_id: "create-embedded-invite-document-group"
authorization: "bearer"
---
# Create embedded invite
`POST /v2/document-groups/{document_group_id}/embedded-invites`
This endpoint allows users to create an embedded signing invite for a document group. Once the invite is created, generate an embedded signing link using [`POST /document-groups/{{document_group_id}}/embedded-invites/{{embedded_invite_id}}/link`](/docs/doc-group-embedded-signing/operations/generate-link-for-embedded-invite-document-group) with the ID you got in the response.
Before sending your request, ensure the following:
* You are the owner of the document group to be signed.
* Every document in the payload is a part of a document group.
* The document group contains at least one document.
* The document group is not part of any other invite (pending or signed).
* At least one document in the document group contains fields.
* Signers' email addresses are unique and do not exceed 150 characters.
* All roles or role IDs in the document group are included in the invite (specifying extra roles will result in an error).
**Action types** in `documents`:
* `sign`: the recipient signs the document.
* `view`: the recipient views the document.
* `approve`: the recipient approves the document without signing or filling fields. Only one approver is allowed per invite step, the step must not include other actions, and all document IDs in the document group must be listed for the approver.
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"
}
```
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 recipient (signer or approver) within the integrated application.
Possible values are: `password`, `email`, `social`, `mfa`, `biometric`, `other`, `none`.
**Note**: The `auth_method` parameter does not influence the recipient's authentication method during the signing or approval session. Use the `authentication` object to configure authentication for the 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_group_id` | string | Yes | ID of the document group. |
## Request Body
**Schema**
```json
{
"type": "object",
"required": [
"invites"
],
"properties": {
"invites": {
"type": "array",
"items": {
"type": "object",
"required": [
"order",
"signers"
],
"properties": {
"order": {
"type": "integer",
"example": 1,
"description": "Order step. On \"order\": 1, all recipients of this step receive an email with the invite at the same time. Only when they complete all the actions, the \"order\": 2 emails are sent."
},
"signers": {
"type": "array",
"items": {
"type": "object",
"required": [
"email",
"auth_method",
"documents"
],
"properties": {
"email": {
"type": "string",
"example": "signer1@email.com",
"description": "Recipient's email to receive the invite."
},
"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."
},
"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."
},
"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."
},
"documents": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"role",
"action"
],
"properties": {
"id": {
"type": "string",
"example": "cd78bf43ce4b454b89d8bcd535437a939687XXXX",
"description": "ID of the document."
},
"role": {
"type": "string",
"example": "Signer 1",
"description": "Recipient role in the document."
},
"action": {
"type": "string",
"example": "sign",
"description": "Action required in the document. Allowed values: `sign`, `view`, `approve`."
}
}
},
"minItems": 1,
"description": "Array of documents in the document group that the recipient is assigned to. For each document in the array, the document ID, role, and action are specified.",
"uniqueItems": true
},
"last_name": {
"type": "string",
"example": "Doe",
"description": "Recipient's last name."
},
"signature": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type of the QES. Allowed values are `eideasy`, `nom151`. For more information, see [QES user guide](/docs/qualified-electronic-signature).",
"x-stoplight": {
"id": "f52xc03m68mhr"
}
}
},
"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": "4l37sc9i5nrai"
}
},
"first_name": {
"type": "string",
"example": "John",
"description": "Recipient'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. Not applicable for `approve` action."
},
"authentication": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "password",
"description": "Authentication type used for the recipient authentication during the signing session. Required inside `authentication` object. Allowed values: `phone`, `password`.",
"x-stoplight": {
"id": "jhnd9v2akswlc"
}
},
"phone": {
"type": "string",
"example": "+1XXXXXXXXX",
"description": "Phone number used to authenticate the recipient. Required inside `authentication` object with the `phone` method.",
"x-stoplight": {
"id": "17bkxyj2hyn20"
}
},
"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`.",
"x-stoplight": {
"id": "05v5ow6u33pl7"
}
},
"password": {
"type": "string",
"example": "123456",
"description": "Password set for the recipient authentication. Required inside the `authentication` object with the `password` authentication type.",
"x-stoplight": {
"id": "djknubzhv860p"
}
},
"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\".",
"x-stoplight": {
"id": "qtiiuw1moy109"
}
}
},
"description": "Authentication settings used to verify the recipient's identity.",
"x-stoplight": {
"id": "sv5qxsfa96acg"
}
},
"delivery_type ": {
"type": "string",
"example": "link",
"description": "Defines how the invite is sent. Allowed values: `email`, `link`."
},
"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`."
},
"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. Allowed values: `blank` - opens the link in the new tab, `self` - opens the link in the same tab. Not applicable for `approve` action."
},
"close_redirect_uri": {
"type": "string",
"example": "https://example.com",
"description": "The link that opens when a recipient clicks **Save Progress and Finish Later** during a signing session or **Close** in view mode. Not applicable for `approve` action.",
"x-stoplight": {
"id": "nydnzpctz8foj"
}
},
"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` and only for sign actions.",
"x-stoplight": {
"id": "tdzp2yb274yqj"
}
},
"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."
},
"decline_redirect_uri": {
"type": "string",
"example": "https://example.com",
"description": "The link that opens after the signing session has been declined by the recipient. Not applicable for `approve` action."
},
"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": "John Doe",
"description": "The text displayed in the Signature field. The signer cannot edit this value. Cannot be used simultaneously with `prefill_signature_name` or `force_new_signature` for the same role."
}
}
},
"minItems": 1,
"description": "Array of recipient objects that must receive their invites at this step. Each object contains: recipient's email address, authentication method, documents they are assigned to, and the role assigned to them in the documents.",
"uniqueItems": true
}
}
},
"minItems": 1,
"description": "Array of invite objects that includes order and settings for different recipients.",
"uniqueItems": true
},
"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`."
}
}
}
```
**Example** (`Request with QES`)
```json
{
"invites": [
{
"order": 1,
"signers": [
{
"email": "signer1@email.com",
"message": "Please review the invoice and sign it at your earliest convenience.",
"subject": "Sign the invoice",
"language": "es",
"documents": [
{
"id": "43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Signer 1",
"action": "sign"
},
{
"id": "ffXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"action": "view"
}
],
"last_name": "Doe",
"signature": {
"type": "eideasy"
},
"first_name": "John",
"auth_method": "none",
"redirect_uri": "https://example.com",
"delivery_type": "email",
"authentication": {
"type": "password",
"password": "12345qwerty"
},
"link_expiration": 15,
"redirect_target": "blank",
"close_redirect_uri": "https://example.com",
"session_expiration": 15,
"decline_redirect_uri": "https://signnow.com",
"prefill_signature_name": "Recipient signature"
}
]
},
{
"order": 2,
"signers": [
{
"email": "signer2@email.com",
"language": "en",
"documents": [
{
"id": "43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Signer 2",
"action": "sign"
}
],
"signature": {
"type": "eideasy"
},
"auth_method": "none",
"authentication": {
"type": "phone",
"phone": "+12025550147",
"method": "phone_call"
}
}
]
}
],
"from_name": "Jane Doe",
"from_email": "sender@email.com"
}
```
**Example** (`Request with approver and signer authentication`)
```json
{
"invites": [
{
"order": 1,
"signers": [
{
"email": "approver@email.com",
"language": "en",
"documents": [
{
"id": "43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Approver 1",
"action": "approve"
},
{
"id": "ffXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Approver 1",
"action": "approve"
},
{
"id": "74XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Approver 1",
"action": "approve"
},
{
"id": "daXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Approver 1",
"action": "approve"
}
],
"last_name": "Williams",
"first_name": "Sarah",
"auth_method": "none",
"authentication": {
"type": "phone",
"phone": "+12025550147",
"method": "sms",
"sms_message": "Verification code is {password}"
}
}
]
},
{
"order": 2,
"signers": [
{
"email": "signer1@email.com",
"message": "Please review the invoice and sign it at your earliest convenience.",
"subject": "Sign the invoice",
"language": "es",
"documents": [
{
"id": "43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Signer 1",
"action": "sign"
},
{
"id": "ffXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"action": "view"
}
],
"last_name": "Doe",
"first_name": "John",
"auth_method": "none",
"redirect_uri": "https://example.com",
"delivery_type": "email",
"authentication": {
"type": "password",
"password": "12345qwerty"
},
"link_expiration": 15,
"redirect_target": "blank",
"close_redirect_uri": "https://example.com",
"session_expiration": 15,
"decline_redirect_uri": "https://signnow.com",
"prefill_signature_name": "Recipient signature"
}
]
},
{
"order": 3,
"signers": [
{
"email": "signer2@email.com",
"language": "en",
"documents": [
{
"id": "43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Signer 2",
"action": "sign"
}
],
"auth_method": "none",
"authentication": {
"type": "phone",
"phone": "+12025550147",
"method": "phone_call"
}
},
{
"email": "signer3@email.com",
"language": "en",
"documents": [
{
"id": "74XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Signer 3",
"action": "sign"
},
{
"id": "daXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"role": "Signer 3",
"action": "sign"
}
],
"auth_method": "none",
"authentication": {
"type": "phone",
"phone": "+12025550147",
"method": "sms",
"sms_message": "Enter the password to unlock your document. Password: {password}"
}
}
]
}
],
"from_name": "Jane Doe",
"from_email": "sender@email.com"
}
```
## Responses
### 201
Returns the ID of the created invite object.
**Example** (`Example 1`)
```json
{
"data": {
"id": "13XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
```
**Example** (`application/json`)
```json
{
"data": {
"id": "13XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
```
### 400
* Document in the payload is not part of document group.
* Document group has no documents.
* Document group has no fields.
* Nonexistent role in payload.
* Not all document roles were used.
* Orders are not unique.
* The order sequence is incorrect.
* Doc ID is not unique for one signer within a step.
* {Document ID + role} must be unique across the entire payload.
* Email is not unique within a single step.
**Validation errors**:
* 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 (should be less than 255 characters).
* The `required_preset_signature_name` contains unsupported characters.
* The `language` is not a string.
* The `language` attribute is incorrect, allowed values: `en`, `fr`, `es`.
* Field `redirect_uri` is not a string.
* Field `redirect_uri` is empty.
* Field `redirect_uri` is not a valid URL.
* Field `decline_redirect_uri` is not a string.
* Field `decline_redirect_uri` is empty.
* Field `decline_redirect_uri` is not a valid URL.
* The `redirect_target` value is not a string.
* The `redirect_target` attribute is incorrect, allowed values: `self`, `blank`.
* The one of `redirect_uri` fields is required when `redirect_target` is added.
* Parameter `redirect_uri` is too long (must not exceed 2048 characters).
* Parameter `decline_redirect_uri` is too long (must not exceed 2048 characters).
* Parameter `delivery_type` is not a string.
* Incorrect `delivery_type` value. Possible values: `email`, `link`.
* Parameter `link_expiration` is not an integer.
* Parameter `link_expiration` is incorrect (must be equal to 15 or more).
* Parameter `link_expiration` is incorrect (must be equal to 45 or less).
* Parameter `link_expiration` can only be used if `delivery_type=email`.
* Parameter `session_expiration` is not an integer.
* Parameter `session_expiration` is out of range.
* Parameter `session_expiration` is used with an incorrect `delivery_type` value.
* Parameter `session_expiration` is used with an incorrect action.
* Parameter `subject` in `signers` is not a string.
* Parameter `subject` in `signers` is empty.
* Parameter `subject` in `signers` is too long.
* Parameter `subject` in `signers` contains unsupported characters.
* Parameter `subject` in `signers` is used when `delivery_type` is not `email`.
* Parameter `message` in `signers` is not a string.
* Parameter `message` in `signers` is empty.
* Parameter `message` in `signers` is too long.
* Parameter `message` in `signers` contains unsupported characters.
* Parameter `message` in `signers` is used when `delivery_type` is not `email`.
* The `prefill_signature_name` format is wrong.
* The `prefill_signature_name` is empty.
* The`prefill_signature_name` contains unsupported characters.
* The `prefill_signature_name` is too long.
**Recipient authentication errors**:
* The `authentication.method` value is incorrect.
* The `authentication` field is empty.
* The `authentication.type` value type is incorrect.
* The `authentication.type` field is required.
* The `authentication.type` field value is incorrect.
* The `authentication.password` value type is incorrect.
* The `authentication.password` field is required.
* The `authentication.method` value type is incorrect.
* The `authentication.method` field is required.
* The `authentication.method` value is incorrect.
* The `authentication.phone` value type is incorrect.
* The `authentication.phone` field is required.
* The `authentication.phone` value is incorrect.
* The `authentication.sms_message` value type is incorrect.
* The `authentication.sms_message` value is too long.
* The `authentication.sms_message` value contains unsupported characters.
* The `authentication.sms_message` must include a {password} placeholder.
* The `authentication` is set for recipients with unsupported actions.
* The `authentication` must be used when the `sign_as_merged` field is set to `true`.
**QES-specific errors**:
* The `signature.type` value is empty.
* The `signature.type` value is not supported.
* Multiple signers were found in a single step.
* Different signature providers assigned to signers.
* The `signature` field type is incorrect.
* The `signature.type` value type is incorrect.
* The user is not part of the organization.
* The organization has no advanced sign provider enabled.
**Approve-action errors**:
* The `action` value is not one of `sign`, `view`, `approve`.
* More than one `approve` action is used in the same invite step.
* An invite step with an `approve` action also includes other actions.
* Not all document group document IDs are listed for the approver.
* The `role` field is missing for an approve action.
**Example** (`Example 1`)
```json
{
"errors": [
{
"code": "19022008",
"message": "The sender organization\u2019s advanced sign provider is not valid."
}
]
}
```
**Example** (`Message is empty`)
```json
{
"errors": [
{
"code": 19021107,
"message": "The `message` field in `signers` must not be empty string."
}
]
}
```
**Example** (`Subject is empty`)
```json
{
"errors": [
{
"code": 19021103,
"message": "The `subject` field in `signers` must not be empty string."
}
]
}
```
**Example** (`Orders not unique`)
```json
{
"errors": [
{
"code": 19017030,
"message": "Orders must be unique."
}
]
}
```
**Example** (`Message is too long`)
```json
{
"errors": [
{
"code": 19021108,
"message": "The `message` field in `signers` must contain no more than 5000 characters."
}
]
}
```
**Example** (`Subject is too long`)
```json
{
"errors": [
{
"code": 19021104,
"message": "The `subject` field in `signers` must contain no more than 1000 characters."
}
]
}
```
**Example** (`signature.type empty`)
```json
{
"errors": [
{
"code": 19021076,
"message": "The `signature.type` must not be empty for elements in the `signers` array."
}
]
}
```
**Example** (`Message is not string`)
```json
{
"errors": [
{
"code": 19021106,
"message": "The `message` field in `signers` must be a string."
}
]
}
```
**Example** (`Subject is not string`)
```json
{
"errors": [
{
"code": 19021102,
"message": "The `subject` field in `signers` must be a string."
}
]
}
```
**Example** (`Invalid order sequence`)
```json
{
"errors": [
{
"code": 19017031,
"message": "Orders must begin with 1 and the increment between orders must be equal to one."
}
]
}
```
**Example** (`Action value is invalid`)
```json
{
"errors": [
{
"code": 19021026,
"message": "The `action` must be one of the following types: `sign`, `view`, `approve`."
}
]
}
```
**Example** (`Authentication is empty`)
```json
{
"errors": [
{
"code": 19021083,
"message": "The authentication field in signers must not be empty."
}
]
}
```
**Example** (`Incorrect delivery_type`)
```json
{
"errors": [
{
"code": 19021064,
"message": "The `delivery_type` field is invalid, allowed values: email, link."
}
]
}
```
**Example** (`link_expiration too big`)
```json
{
"errors": [
{
"code": 19022006,
"message": "The `link_expiration` field must be less than or equal to 45 minutes."
}
]
}
```
**Example** (`User not in organization`)
```json
{
"errors": [
{
"code": 19022009,
"message": "Organization is required to send an invite with advanced signing."
}
]
}
```
**Example** (`delivery_type not string`)
```json
{
"errors": [
{
"code": 19021063,
"message": "The `delivery_type` field must be a string."
}
]
}
```
**Example** (`Redundant link_expiration`)
```json
{
"errors": [
{
"code": 19021067,
"message": "The `link_expiration` field must be used if the `delivery_type` field contains `email`."
}
]
}
```
**Example** (`Role required for approve`)
```json
{
"errors": [
{
"code": 19021035,
"message": "Field `role` is required for sign, approve actions."
}
]
}
```
**Example** (`No advanced sign providers`)
```json
{
"errors": [
{
"code": 19022008,
"message": "The sender organization\u2019s advanced sign provider is not valid."
}
]
}
```
**Example** (`link_expiration too little`)
```json
{
"errors": [
{
"code": 19021066,
"message": "The `link_expiration` field must be greater than or equal to 15 minutes."
}
]
}
```
**Example** (`Nonexistent role in payload`)
```json
{
"errors": [
{
"code": 19018004,
"message": "Role {{ roleName }} is not found on document {{ documentUniqueId }}."
}
]
}
```
**Example** (`Signature type is incorrect`)
```json
{
"errors": [
{
"code": 19021081,
"message": "The `signature` field in `signers` must be an array."
}
]
}
```
**Example** (`link_expiration not integer`)
```json
{
"errors": [
{
"code": 19021065,
"message": "The `link_expiration` field must be an integer."
}
]
}
```
**Example** (`Document group has no fields`)
```json
{
"errors": [
{
"code": 19018002,
"message": "At least one document in document group must contain fields."
}
]
}
```
**Example** (`signature.type not supported`)
```json
{
"errors": [
{
"code": 19021077,
"message": "The `signature.type` attribute is not valid, allowed values: \"eideasy\", \"nom151\"."
}
]
}
```
**Example** (`Approver missing document IDs`)
```json
{
"errors": [
{
"code": 19022014,
"message": "For an `approve` action, all document IDs from the document group must be specified."
}
]
}
```
**Example** (`Different signature providers`)
```json
{
"errors": [
{
"code": 19021079,
"message": "The `signature.type` fields must be the same for all signers."
}
]
}
```
**Example** (`Multiple signers for one step`)
```json
{
"errors": [
{
"code": 19021080,
"message": "Must have only one signer per step if a signature field exists."
}
]
}
```
**Example** (`session_expiration for viewer`)
```json
{
"errors": [
{
"code": 19021075,
"message": "The `session_expiration` field must be used if at least one of the `action` field in `documents` contains `sign`."
}
]
}
```
**Example** (`session_expiration not integer`)
```json
{
"errors": [
{
"code": 19021072,
"message": "The `session_expiration` field must be an integer."
}
]
}
```
**Example** (`Authentication.type is required`)
```json
{
"errors": [
{
"code": 19021085,
"message": "The authentication.type field in signers is required."
}
]
}
```
**Example** (`Document group has no documents`)
```json
{
"errors": [
{
"code": 19018001,
"message": "Document group must contain at least one document."
}
]
}
```
**Example** (`More than one approve in a step`)
```json
{
"errors": [
{
"code": 19021122,
"message": "Only one `approve` action is allowed per invite step."
}
]
}
```
**Example** (`prefill_signature_name is empty`)
```json
{
"errors": [
{
"code": 19021121,
"message": "The `prefill_signature_name` value must not be empty string."
}
]
}
```
**Example** (`prefill_signature_name too long`)
```json
{
"errors": [
{
"code": 19021120,
"message": "The `prefill_signature_name` is too long. It should have 255 characters or less."
}
]
}
```
**Example** (`session_expiration out of range`)
```json
{
"errors": [
{
"code": 19021073,
"message": "The `session_expiration` must be between 15 and 1440."
}
]
}
```
**Example** (`Authentication.phone is required`)
```json
{
"errors": [
{
"code": 19021093,
"message": "The authentication.phone field in signers is required."
}
]
}
```
**Example** (`Not all document roles were used`)
```json
{
"errors": [
{
"code": 19018003,
"message": "Role {{ roleName }} on document {{ documentUniqueId }} was not specified."
}
]
}
```
**Example** (`session_expiration with no email`)
```json
{
"errors": [
{
"code": 19021074,
"message": "The `session_expiration` field must be used if the `delivery_type` field contains `email`."
}
]
}
```
**Example** (`Authentication.method is required`)
```json
{
"errors": [
{
"code": 19021090,
"message": "The authentication.method field in signers is required."
}
]
}
```
**Example** (`Authentication with sign_as_merged`)
```json
{
"errors": [
{
"code": 19021101,
"message": "The authentication field must be used if the sign_as_merged field is set to true."
}
]
}
```
**Example** (`Authentication.method is incorrect`)
```json
{
"errors": [
{
"code": 19021082,
"message": "The `authentication.method` field in `signers` is invalid."
}
]
}
```
**Example** (`Authentication.password is required`)
```json
{
"errors": [
{
"code": 19021088,
"message": "The authentication.password field is required."
}
]
}
```
**Example** (`Email is not unique within one step`)
```json
{
"errors": [
{
"code": 19017032,
"message": "Email must be unique within one invite step."
}
]
}
```
**Example** (`prefill_signature_name not a string`)
```json
{
"errors": [
{
"code": 19021118,
"message": "Field `prefill_signature_name` must be a string."
}
]
}
```
**Example** (`Approve step mixed with other actions`)
```json
{
"errors": [
{
"code": 19021123,
"message": "An invite step with an `approve` action must not include any other actions."
}
]
}
```
**Example** (`Authentication.phone type is incorrect`)
```json
{
"errors": [
{
"code": 19021092,
"message": "The authentication.phone field in signers must be a string."
}
]
}
```
**Example** (`Authentication.sms_message is too long`)
```json
{
"errors": [
{
"code": 19021096,
"message": "The authentication.sms_message field in signers must contain no more than 140 characters."
}
]
}
```
**Example** (`Authentication.type value is incorrect`)
```json
{
"errors": [
{
"code": 19021086,
"message": "The `authentication.type` field in signers is invalid."
}
]
}
```
**Example** (`signature.type value type is incorrect`)
```json
{
"errors": [
{
"code": 19021078,
"message": "The `signature.type` must be a string."
}
]
}
```
**Example** (`Authentication.method type is incorrect`)
```json
{
"errors": [
{
"code": 19021089,
"message": "The authentication.method field in signers must be a string."
}
]
}
```
**Example** (`Authentication.phone value is incorrect`)
```json
{
"errors": [
{
"code": 19021094,
"message": "The authentication.phone field in signers contains an invalid phone number."
}
]
}
```
**Example** (`Message contains unsupported characters`)
```json
{
"errors": [
{
"code": 19021109,
"message": "The `message` field in `signers` must not contain 4-byte characters."
}
]
}
```
**Example** (`Subject contains unsupported characters`)
```json
{
"errors": [
{
"code": 19021105,
"message": "The `subject` field in `signers` must not contain 4-byte characters."
}
]
}
```
**Example** (`Authentication.method value is incorrect`)
```json
{
"errors": [
{
"code": 19021091,
"message": "The `authentication.method` field in `signers` is invalid."
}
]
}
```
**Example** (`Message is used with wrong delivery_type`)
```json
{
"errors": [
{
"code": 19021110,
"message": "In `signers`, the `subject` or `message` fields must be used if the `delivery_type` field contains `email`."
}
]
}
```
**Example** (`Subject is used with wrong delivery_type`)
```json
{
"errors": [
{
"code": 19021110,
"message": "In `signers`, the `subject` or `message` fields must be used if the `delivery_type` field contains `email`."
}
]
}
```
**Example** (`Authentication.password type is incorrect`)
```json
{
"errors": [
{
"code": 19021087,
"message": "The authentication.password field in signers must be a string."
}
]
}
```
**Example** (`Authentication set for unsupported actions`)
```json
{
"errors": [
{
"code": 19021100,
"message": "The authentication field must be used if at least one action field in documents contains sign."
}
]
}
```
**Example** (`Authentication.sms_message type is incorrect`)
```json
{
"errors": [
{
"code": 19021095,
"message": "The authentication.sms_message field in signers must be a string."
}
]
}
```
**Example** (`Authentication.sms_message without placeholder`)
```json
{
"errors": [
{
"code": 19021098,
"message": "The authentication.sms_message field in signers must contain {password} placeholder."
}
]
}
```
**Example** (`Doc Id is not unique for one signer within step`)
```json
{
"errors": [
{
"code": 19017023,
"message": "Document id must be unique for signer within one step."
}
]
}
```
**Example** (`prefill_signature_name contains 4-byte characters`)
```json
{
"errors": [
{
"code": 19021119,
"message": "UTF 4-byte characters in `prefill_signature_name` are not supported."
}
]
}
```
**Example** (`Authentication.sms_message has unsupported symbols`)
```json
{
"errors": [
{
"code": 19021097,
"message": "The authentication.sms_message field in signers must not contain 4-byte characters."
}
]
}
```
**Example** (`{Document id + role} must be unique in all payload`)
```json
{
"errors": [
{
"code": 19017033,
"message": "Document id with role must be unique."
}
]
}
```
**Example** (`Document in the payload is not part of document group`)
```json
{
"errors": [
{
"code": 19018005,
"message": "Document {documentUniqueId} is not part of the document group."
}
]
}
```
### 403
User doesn't own the document group.
**Example** (`User doesn't own the document group`)
```json
{
"code": 19001010,
"message": "Current user is not document group owner."
}
```
### 422
Group invite already exists.
**Example** (`Group invite already exists`)
```json
{
"errors": [
{
"code": 19001030,
"message": "A group invite already exists for this document group."
}
]
}
```
## Code Examples
> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.
### cURL
```bash
curl -X POST \
"https://api.signnow.com/v2/document-groups/{document_group_id}/embedded-invites" \
-H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"invites": [{"order": 1, "signers": [{"email": "signer1@email.com", "message": "Please review the invoice and sign it at your earliest convenience.", "subject": "Sign the invoice", "language": "es", "documents": [{"id": "43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "role": "Signer 1", "action": "sign"}, {"id": "ffXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "action": "view"}], "last_name": "Doe", "signature": {"type": "eideasy"}, "first_name": "John", "auth_method": "none", "redirect_uri": "https://example.com", "delivery_type": "email", "authentication": {"type": "password", "password": "12345qwerty"}, "link_expiration": 15, "redirect_target": "blank", "close_redirect_uri": "https://example.com", "session_expiration": 15, "decline_redirect_uri": "https://signnow.com", "prefill_signature_name": "Recipient signature"}]}, {"order": 2, "signers": [{"email": "signer2@email.com", "language": "en", "documents": [{"id": "43XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "role": "Signer 2", "action": "sign"}], "signature": {"type": "eideasy"}, "auth_method": "none", "authentication": {"type": "phone", "phone": "+12025550147", "method": "phone_call"}}]}], "from_name": "Jane Doe", "from_email": "sender@email.com"}'
```
---
*Full reference: https://docs.signnow.com/docs/doc-group-embedded-signing/operations/create-embedded-invite-document-group*