---
title: "Invite to sign doc group"
url: "https://docs.signnow.com/docs/doc-group-field-invite/operations/invite-to-sign-document-group"
type: "endpoint"
section: "doc-group-field-invite"
slug: "doc-group-field-invite/operations/invite-to-sign-document-group"
method: "POST"
path: "/documentgroup/{document_group_id}/groupinvite"
operation_id: "invite-to-sign-document-group"
authorization: "bearer"
---

# Invite to sign doc group

`POST /documentgroup/{document_group_id}/groupinvite`

This endpoint allows users to create an invite for signing a document group. You can configure a multistep workflow, where different recipients act on the document group at different stages.

Recipients can receive the invite by email or by SMS: identify a recipient by `email` for email delivery or by `phone_invite` for SMS delivery. You can combine email and SMS recipients in a single request. For more information, see the [SMS invite guide](/docs/sms-invite).

Each invite step includes:

- `order`: the sequence number of the step.
- `invite_actions`: an array of objects specifying who is invited and the action they must perform:

    - **`sign`**: The recipient can sign or fill out the document.
    - **`approve`**: The recipient can review the document to approve or decline it.
    - **`view`**: The recipient can only review the document without making changes.
    
- `invite_emails`: an array for customizing the emails sent to recipients at that step.
- `invite_sms`: an array for customizing the SMS invites sent to recipients at that step: custom SMS text (`sms_message`), expiration, and reminder settings.

Once all invite actions in a step are completed, the system sends the emails or SMS messages for the next step. When all steps are complete, completion emails are triggered.

To invite a **signing group**, use the `email_groups` field. A signing group includes multiple email addresses, and the step is marked complete as soon as any member of the group signs. You can either use an existing group or define a new one by providing a 40-character ID, a group name, and the list of recipient emails.

To create a signing group separately, see [Create contact group](/docs/contact-groups/operations/post-v2-crm-groups).

Learn more about an [Invite to sign a document group](/docs/invite-to-sign#send-a-document-group-for-signature).

<details>

**<summary>Use additional attributes to customize signing experience</summary>**

Parameter | Description | Example
---------|----------|---------
 `reassign` | A recipient can forward the invite by clicking **More Actions** > **Forward Invite** and entering an email address. | <img src="/reference-assets/images/Screenshots with attribute explanations/Field invite/reassign.png" alt="Forward invite"> 
 `force_new_signature` | A recipient must create a new signature for each signature field. | <img src="/reference-assets/images/Screenshots with attribute explanations/Field invite/Force_new_signature.png" alt="Force new signature">
 `prefill_signature_name` | A string with a signature name that appears when a signer clicks a signature field. The signer can edit the signature.|
 `required_preset_signature_name` | A string with a signature name that appears when a signer clicks a signature field. The signer cannot edit the signature. |
 `decline_by_signature` | When a signer clicks a signature field, they see two options: sign the fields and decline the document group. | <img src="/reference-assets/images/Screenshots with attribute explanations/Field invite/Decline_by_signature.png" alt="Decline by signature">
 `authentication_type` | Requires a recipient to enter a password or a code before viewing the document group. For more information, see [Two-factor authentication](/docs/two-factor-authentication). | <img src="/reference-assets/images/Screenshots with attribute explanations/Field invite/DG_authentication.png" alt="Password_authentication">
</details>

## Authorization

bearer

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_group_id` | string | Yes | The ID of the document group |

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "invite_steps"
  ],
  "properties": {
    "cc": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of cc email addresses."
    },
    "order_type": {
      "enum": [
        "at_the_same_time",
        "recipient_order",
        "advanced_order",
        null
      ],
      "type": "string",
      "x-nullable": true,
      "description": "Recipient routing rule applied to all recipients in the invite. `at_the_same_time` - all at once; `recipient_order` - sequential by `order` parameter; `advanced_order` - advanced rules."
    },
    "email_groups": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "emails"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Signing group ID. If you created your own ID, make sure that it's 40 characters long.",
            "x-stoplight": {
              "id": "ftm8fhfa4sx96"
            }
          },
          "name": {
            "type": "string",
            "description": "Signing group name",
            "x-stoplight": {
              "id": "6u0opiomemub1"
            }
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "email"
              ],
              "properties": {
                "email": {
                  "type": "string",
                  "description": "Email address in the signing group. Must be unique within a group.",
                  "x-stoplight": {
                    "id": "nmhbd010yzp4l"
                  }
                }
              },
              "x-stoplight": {
                "id": "ge2dl9pzwvwfm"
              }
            },
            "description": "List all the email addresses that should receive an invite within a group, no matter if you are using an existing email group or a new one.",
            "x-stoplight": {
              "id": "ngdzqehm8e1ki"
            }
          }
        },
        "x-stoplight": {
          "id": "dh0e12s3p4bwd"
        }
      },
      "description": "Defines a signing group. Required if at least one step contains a signing group (`email_group`). You can use both an existing email group or create your own.",
      "x-stoplight": {
        "id": "6bsyxhwpmmomu"
      }
    },
    "invite_steps": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "order",
          "invite_actions"
        ],
        "properties": {
          "order": {
            "type": "integer",
            "description": "Integer, order of signing step: 1 - the recipient(s)  sign the document group first, then the document group is sent to 2,3 etc. Several recipients can hold the same order of signing."
          },
          "invite_sms": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "phone_invite"
              ],
              "properties": {
                "reminder": {
                  "type": "object",
                  "properties": {
                    "remind_after": {
                      "type": "number",
                      "maximum": 179,
                      "minimum": 1,
                      "description": "Number of days after sending the invite when the recipient receives a reminder SMS. Must be less than `expiration_days`."
                    },
                    "remind_before": {
                      "type": "number",
                      "maximum": 179,
                      "minimum": 1,
                      "description": "Number of days before the invite expires when the recipient receives a reminder SMS. Must be less than `expiration_days`."
                    },
                    "remind_repeat": {
                      "type": "number",
                      "maximum": 7,
                      "minimum": 1,
                      "description": "Number of days between each reminder sent to the recipient."
                    }
                  },
                  "description": "Settings for sending automatic reminders."
                },
                "sms_message": {
                  "type": "string",
                  "example": "Hi, here is a document for signature from {sender_email}",
                  "maxLength": 140,
                  "description": "Custom text of the SMS invite, max `140` characters. Supports the `{sender_email}` placeholder that is automatically replaced with the sender's email address. The link to the document group and an opt-out notice are automatically added at the end of the SMS. Without this parameter, the recipient receives the default message: \"{sender email} has sent you a document. Follow the link to view the document\". Custom SMS messages require an API free trial, an active API subscription, or a Site License."
                },
                "phone_invite": {
                  "type": "string",
                  "example": "+14075985199",
                  "description": "Recipient's phone number for the SMS invite. Must match the `phone_invite` value of this recipient in `invite_actions`."
                },
                "expiration_days": {
                  "type": "number",
                  "default": 30,
                  "maximum": 180,
                  "minimum": 3,
                  "description": "Number of days before the invite expires."
                }
              }
            },
            "description": "Objects that define a custom SMS message, expiration, and reminder settings for each SMS recipient within a step. SMS recipients are identified by `phone_invite` instead of `email` in `invite_actions`."
          },
          "invite_emails": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "email"
              ],
              "properties": {
                "email": {
                  "type": "string",
                  "format": "email",
                  "description": "Recipient's email address"
                },
                "message": {
                  "type": "string",
                  "description": "Custom email message for the recipient. Requires a paid API plan, an API free trial, or a Site License."
                },
                "subject": {
                  "type": "string",
                  "description": "Custom email subject for the recipient. Requires a paid API plan, an API free trial, or a Site License."
                },
                "reminder": {
                  "type": "object",
                  "properties": {
                    "remind_after": {
                      "type": "number",
                      "maximum": 179,
                      "minimum": 1,
                      "description": "x days after the invite, a recipient gets a reminder email. Must be less than `expiration_days`"
                    },
                    "remind_before": {
                      "type": "number",
                      "maximum": 179,
                      "minimum": 1,
                      "description": "x days before expiration, a recipient gets a reminder email. Must be less than `expiration_days`"
                    },
                    "remind_repeat": {
                      "type": "number",
                      "maximum": 7,
                      "minimum": 1,
                      "description": "A recipient gets a reminder email each x days after the invite is sent"
                    }
                  },
                  "description": "Settings for sending automatic reminder emails."
                },
                "email_group": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "The name of the contact group.",
                      "x-stoplight": {
                        "id": "cpunlkhtfa0sv"
                      }
                    }
                  },
                  "description": "A contact group of recipients, for example, [CRM Contact group](/docs/contact-groups/operations/post-v2-crm-groups).",
                  "x-stoplight": {
                    "id": "8j65i1jlx4gka"
                  }
                },
                "expiration_days": {
                  "type": "number",
                  "default": 30,
                  "maximum": 180,
                  "minimum": 3,
                  "description": "In x days, the invite expires"
                }
              }
            },
            "description": "Objects that define custom email subject, email message, expiration and reminder settings for each recipient within a step."
          },
          "invite_actions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "role_name",
                "action",
                "document_id"
              ],
              "properties": {
                "email": {
                  "type": "string",
                  "format": "email",
                  "description": "Recipient's email address. The invite is delivered by email. Identify each recipient by `email`, `phone_invite`, or `email_group` \u2014 only one of these parameters at a time."
                },
                "action": {
                  "type": "string",
                  "description": "Allowed action with a document. Possible values: `view`, `sign`, `approve`. The `approve` action must be assigned to all documents in the document group. The `view` action can be assigned to any subset of documents in the group."
                },
                "language": {
                  "type": "string",
                  "description": "Sets the language of the signing session and notification emails for the signer. Possible values: `en` for English, `es` for Spanish, and `fr` for French. If not set, the language is determined by the language of your signNow account. If emails are branded, you can set up [your own](/docs/guides-branding#language-branding) email texts in different languages.",
                  "x-stoplight": {
                    "id": "b743u1ldxugp1"
                  }
                },
                "role_name": {
                  "type": "string",
                  "description": "Recipient's role name in the document (can be used to identify fields in the document assigned to this particular recipient). The `role` parameter is also supported as an equivalent of `role_name`."
                },
                "signature": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Type of QES signature. Possible values: `eideasy`,` eideasy-pdf`, and `nom151`. All signers in the invite must have the same signature type.",
                      "x-stoplight": {
                        "id": "4l7pk80x2ug82"
                      }
                    }
                  },
                  "description": "This object is used to request QES signatures from signers. To use it, a user must be a member of an organization (workspace) with QES settings enabled. If QES is used, it must be used for all signers in the invite.<br>For more information, see [QES user guide](/docs/qualified-electronic-signature).",
                  "x-stoplight": {
                    "id": "7eghm82e9pwme"
                  }
                },
                "document_id": {
                  "type": "string",
                  "description": "ID of the document on which actions are required from this recipient."
                },
                "email_group": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "The name of the contact group.",
                      "x-stoplight": {
                        "id": "woou5tg76ubps"
                      }
                    }
                  },
                  "description": "A contact group of recipients, for example, [CRM Contact group](/docs/contact-groups/operations/post-v2-crm-groups).",
                  "x-stoplight": {
                    "id": "pfen0o1om14d5"
                  }
                },
                "phone_invite": {
                  "type": "string",
                  "example": "+14075985199",
                  "description": "Recipient's phone number. The invite is delivered by SMS instead of email. Use instead of `email`. To customize the SMS text, expiration, or reminders, add an object with the same phone number to the `invite_sms` array of this step."
                },
                "redirect_uri": {
                  "type": "string",
                  "example": "https://www.signnow.com/",
                  "description": "The link that opens after the recipient completes the document.\n\n",
                  "x-stoplight": {
                    "id": "z01y5i3duhee2"
                  }
                },
                "allow_reassign": {
                  "type": "string",
                  "description": "Whether or not to allow recipients reassign this invite to another email address. Possible values: \"0\" - not allowed, \"1\" - allowed."
                },
                "authentication": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Type of signer's identity verification. Possible values: `\"password\"` or `\"phone\"`."
                    },
                    "phone": {
                      "type": "string",
                      "description": "Required in case of `\"type\"`: `\"phone\"`. User's phone number."
                    },
                    "value": {
                      "type": "string",
                      "description": "Required in case of `\"type\"`: `\"password\"`. The password for user authentication."
                    },
                    "method": {
                      "type": "string",
                      "description": "Required in case of `\"type\"`: `\"phone\"`. Possible values: `\"phone_call`\", `\"sms\"`."
                    },
                    "message": {
                      "type": "string",
                      "description": "In case of `\"method\"`: `\"sms\"` - custom SMS message, max 140 characters. Customizing the 2FA SMS message requires an API free trial, an active API subscription, or a Site License."
                    }
                  },
                  "description": "Object that contains the type of signer's identity verification, phone number or password."
                },
                "payment_request": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "In this case, must be \"fixed\".",
                      "x-stoplight": {
                        "id": "8eozczxgftexj"
                      }
                    },
                    "amount": {
                      "type": "string",
                      "description": "The payment amount requested.",
                      "x-stoplight": {
                        "id": "pgiupb58ob7i4"
                      }
                    },
                    "currency": {
                      "type": "string",
                      "description": "The payment currency requested.",
                      "x-stoplight": {
                        "id": "1w4yo844v8oqv"
                      }
                    },
                    "merchant_id": {
                      "type": "string",
                      "description": "The ID of the merchant account added to your organization (workspace).",
                      "x-stoplight": {
                        "id": "74htcsy6un1ra"
                      }
                    }
                  },
                  "description": "Object that contains details about the payment request.",
                  "x-stoplight": {
                    "id": "iekmitepg8epa"
                  }
                },
                "redirect_target": {
                  "type": "string",
                  "default": "blank",
                  "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.",
                  "x-stoplight": {
                    "id": "7vhkx05u09xgd"
                  }
                },
                "close_redirect_uri": {
                  "type": "string",
                  "description": "The link that opens when a signer clicks\u00a0**Save Progress and Finish Later**\u00a0during a signing session or\u00a0**Close**\u00a0in view mode. Available for `sign ` action.",
                  "x-stoplight": {
                    "id": "hoyx0baz5erbv"
                  }
                },
                "decline_by_signature": {
                  "type": "string",
                  "description": "Whether or not to allow recipients decline to sign the invite."
                },
                "decline_redirect_uri": {
                  "type": "string",
                  "description": "The URL that opens after the recipient declines the document. Available for `sign` action.",
                  "x-stoplight": {
                    "id": "179b6xp2pyvyl"
                  }
                },
                "prefill_signature_name": {
                  "type": "string",
                  "example": "Jane Doe",
                  "maxLength": 255,
                  "description": "The text displayed in the Signature field. The signer can edit this value."
                },
                "is_close_redirect_canceled": {
                  "type": "boolean",
                  "default": false,
                  "description": "Specifies whether the save progress redirect setting is canceled for the organization (workspace).`true`\u00a0\u2013 the redirect is canceled;`false`\u00a0\u2013 the redirect remains active.",
                  "x-stoplight": {
                    "id": "vmbf2a9u6y1uz"
                  }
                },
                "is_finish_redirect_canceled": {
                  "type": "boolean",
                  "default": false,
                  "description": "Specifies whether the completion redirect setting is canceled for the organization (workspace).`true`\u00a0\u2013 the redirect is canceled;`false`\u00a0\u2013 the redirect remains active.",
                  "x-stoplight": {
                    "id": "vmbf2a9u6y1uz"
                  }
                },
                "is_decline_redirect_canceled": {
                  "type": "boolean",
                  "default": false,
                  "description": "Specifies whether the decline redirect setting is canceled for the organization (workspace).`true`\u00a0\u2013 the redirect is canceled;`false`\u00a0\u2013 the redirect remains active.",
                  "x-stoplight": {
                    "id": "vmbf2a9u6y1uz"
                  }
                },
                "required_preset_signature_name": {
                  "type": "string",
                  "example": "Jane 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."
                }
              }
            },
            "description": "Objects that define recipients (email addresses, phone numbers for SMS delivery, or signing groups) and invite actions, roles and documents assigned to each recipient within a step."
          }
        }
      },
      "description": "Steps of the document group invite. Every step contains the `order` number, `invite_emails`, `invite_sms`, and `invite_actions` within this step."
    },
    "sign_as_merged": {
      "type": "boolean",
      "default": true,
      "description": "If true, allows API user to send an invite which opens as merged document group in a single document."
    },
    "client_timestamp": {
      "type": "integer",
      "description": "The timestamp of the document group invite."
    },
    "general_reminder": {
      "type": "object",
      "properties": {
        "remind_after": {
          "type": "integer",
          "description": "Days after invite is sent before a reminder is delivered. Must be less than `general_expiration_days`."
        },
        "remind_before": {
          "type": "integer",
          "description": "Days before expiration when a reminder is delivered. Must be less than `general_expiration_days`."
        },
        "remind_repeat": {
          "type": "integer",
          "description": "Days between repeated reminders."
        }
      },
      "x-nullable": true,
      "description": "Default `reminder` applied to all recipients in the invite."
    },
    "completion_emails": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the completion email recipient."
          },
          "message": {
            "type": "string",
            "description": "Custom message for the completion email. Requires a paid API plan, an API free trial, or a Site License."
          },
          "subject": {
            "type": "string",
            "description": "Custom subject for the completion email. Requires a paid API plan, an API free trial, or a Site License."
          },
          "disable_document_attachment": {
            "type": "integer",
            "description": "Whether to disable sending document attachments with the completion email. Possible values: 0 - enable document attachment, 1 - disable document attachment."
          }
        }
      },
      "description": "Object that contains email addresses and custom settings for sending emails about completing the invite."
    },
    "general_expiration_days": {
      "type": "integer",
      "example": 30,
      "maximum": 180,
      "minimum": 1,
      "x-nullable": true,
      "description": "Default `expiration_days` applied to all recipients in the invite. Min: `1`, Max: `180`. Default: `30`."
    },
    "general_expiration_time": {
      "type": "integer",
      "x-nullable": true,
      "description": "Default expiration timestamp (Unix time, seconds) applied to all recipients in the invite."
    }
  }
}
```

**Example** (`Invite with QES`)

```json
{
  "invite_steps": [
    {
      "order": 1,
      "invite_actions": [
        {
          "email": "signer1@email.com",
          "action": "sign",
          "role_name": "Signer 1",
          "signature": {
            "type": "eideasy"
          },
          "document_id": "6e9580fa76ba4edca18fa6e680a36d10a6bab503"
        }
      ]
    },
    {
      "order": 2,
      "invite_actions": [
        {
          "email": "signer2@email.com",
          "action": "sign",
          "role_name": "Signer 2",
          "signature": {
            "type": "eideasy"
          },
          "document_id": "c4aff212145b40888cd75e3c73c978484258c043"
        }
      ]
    }
  ]
}
```

**Example** (`Invite to an email group`)

```json
{
  "email_groups": [
    {
      "id": "signing_group_id",
      "name": "Signing Group Name",
      "emails": [
        {
          "email": "signer1@email.com"
        },
        {
          "email": "signer2@email.com"
        }
      ]
    }
  ],
  "invite_steps": [
    {
      "order": 1,
      "invite_emails": [
        {
          "subject": "Subject",
          "email_group": {
            "name": "Signing Group Name"
          }
        }
      ],
      "invite_actions": [
        {
          "action": "sign",
          "role_name": "Recipient 1",
          "document_id": "4eXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "email_group": {
            "name": "Signing Group Name"
          }
        },
        {
          "action": "sign",
          "role_name": "Recipient 1",
          "document_id": "5aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "email_group": {
            "name": "Signing Group Name"
          }
        }
      ]
    }
  ],
  "sign_as_merged": true,
  "client_timestamp": 0,
  "completion_emails": [
    {
      "email_group": {
        "name": "Signing Group Name"
      }
    }
  ]
}
```

**Example** (`Mixed email and SMS invite`)

```json
{
  "cc": [
    "cc_recipient1@email.com",
    "cc_recipient2@email.com"
  ],
  "order_type": "recipient_order",
  "invite_steps": [
    {
      "order": 1,
      "invite_sms": [
        {
          "reminder": {
            "remind_after": 3,
            "remind_before": 5,
            "remind_repeat": 7
          },
          "sms_message": "Hi, here is a document for signature from {sender_email}",
          "phone_invite": "+14075985199",
          "expiration_days": 30
        }
      ],
      "invite_actions": [
        {
          "action": "sign",
          "role_name": "Buyer",
          "document_id": "XXXXX56dc7d3430ba89514667ce4f32da7b33f76",
          "phone_invite": "+14075985199",
          "redirect_uri": "https://example.com",
          "authentication": {
            "type": "phone",
            "phone": "+14075985199",
            "method": "sms",
            "message": "Enter the password to unlock the document: {password}"
          },
          "redirect_target": "blank",
          "close_redirect_uri": "https://close-redirect-uri.com",
          "show_decline_button": true,
          "decline_by_signature": "0",
          "decline_redirect_uri": "https://signnow.com",
          "prefill_signature_name": "Buyer signature"
        }
      ]
    },
    {
      "order": 2,
      "invite_emails": [
        {
          "email": "seller@email.com",
          "message": "Please contact for any questions",
          "subject": "Review and sign documents",
          "reminder": {
            "remind_after": 3,
            "remind_before": 5,
            "remind_repeat": 7
          },
          "expiration_days": 30
        }
      ],
      "invite_actions": [
        {
          "email": "seller@email.com",
          "action": "sign",
          "role_name": "Seller",
          "document_id": "XXXXX56dc7d3430ba89514667ce4f32da7b33f76",
          "redirect_uri": "https://example.com",
          "allow_reassign": "0",
          "authentication": {
            "type": "password",
            "value": "1233456"
          },
          "i_am_recipient": false,
          "redirect_target": "blank",
          "allow_forwarding": false,
          "close_redirect_uri": "https://close-redirect-uri.com",
          "show_decline_button": true,
          "decline_by_signature": "0",
          "decline_redirect_uri": "https://signnow.com",
          "prefill_signature_name": "Seller signature"
        }
      ]
    }
  ],
  "sign_as_merged": true,
  "general_reminder": {
    "remind_after": 3,
    "remind_before": 5,
    "remind_repeat": 7
  },
  "completion_emails": [],
  "general_expiration_days": 30
}
```

**Example** (`Invite with payment request`)

```json
{
  "cc": [
    "cc_recipient1@email.com",
    "cc_recipient2@email.com"
  ],
  "invite_steps": [
    {
      "order": 1,
      "invite_emails": [
        {
          "email": "signer1@email.com",
          "message": "Message",
          "subject": "Subject",
          "expiration_days": 0
        }
      ],
      "invite_actions": [
        {
          "email": "signer1@email.com",
          "action": "sign",
          "role_name": "Recipient 1",
          "document_id": "4eXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "authentication": {
            "type": "password",
            "value": "Password123@"
          },
          "payment_request": {
            "type": "calculated",
            "currency": "USD",
            "field_id": "eb1dc1e1946f47cd87fa4a63664803bddba6fff",
            "merchants": [
              "5ef7e3853f4a4624a037d90d20513a195937dxxx"
            ],
            "field_name": "payment_buyer",
            "field_type": "text_fields"
          }
        }
      ]
    }
  ],
  "sign_as_merged": true,
  "client_timestamp": 0,
  "completion_emails": [
    {
      "email": "signer1@email.com",
      "message": "Message",
      "subject": "Subject",
      "disable_document_attachment": 0
    }
  ]
}
```

**Example** (`Invite with language settings`)

```json
{
  "invite_steps": [
    {
      "order": 1,
      "invite_emails": [
        {
          "email": "signer1@email.com",
          "message": "Hi, this is an invite to sign a document group from sender@email.com.",
          "subject": "You've received a document group invite",
          "expiration_days": 30
        }
      ],
      "invite_actions": [
        {
          "email": "signer1@email.com",
          "action": "sign",
          "language": "es",
          "role_name": "Signer 1",
          "document_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "redirect_uri": "https://example.com",
          "allow_reassign": "0",
          "decline_by_signature": "0"
        },
        {
          "email": "signer4@email.com",
          "action": "view",
          "role_name": "Viewer",
          "document_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        }
      ]
    },
    {
      "order": 2,
      "invite_emails": [
        {
          "email": "signer2@email.com",
          "message": "Hi, this is an invite to sign a document group from sender@email.com.",
          "subject": "You've received a document group invite",
          "reminder": 0,
          "expiration_days": 30
        }
      ],
      "invite_actions": [
        {
          "email": "signer2@email.com",
          "action": "sign",
          "language": "fr",
          "role_name": "Signer 2",
          "document_id": "53XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "redirect_uri": "https://example.com",
          "allow_reassign": "0",
          "close_redirect_uri": "https://close-redirect-uri.com",
          "decline_by_signature": "0"
        }
      ]
    }
  ],
  "sign_as_merged": true,
  "completion_emails": []
}
```

**Example** (`Invite with signers, approvers, viewers, and CC-recipients`)

```json
{
  "cc": [
    "cc_recipient1@email.com",
    "cc_recipient2@email.com"
  ],
  "order_type": "recipient_order",
  "invite_steps": [
    {
      "order": 1,
      "invite_emails": [
        {
          "email": "buyer@email.com",
          "message": "Please contact for any questions",
          "subject": "Review and sign documents",
          "reminder": {
            "remind_after": 3,
            "remind_before": 5,
            "remind_repeat": 7
          },
          "expiration_days": 30
        }
      ],
      "invite_actions": [
        {
          "email": "buyer@email.com",
          "action": "sign",
          "role_name": "Buyer",
          "document_id": "XXXXX56dc7d3430ba89514667ce4f32da7b33f76",
          "redirect_uri": "https://example.com",
          "allow_reassign": "0",
          "authentication": {
            "type": "password",
            "value": "1233456"
          },
          "i_am_recipient": false,
          "redirect_target": "blank",
          "allow_forwarding": false,
          "close_redirect_uri": "https://close-redirect-uri.com",
          "show_decline_button": true,
          "decline_by_signature": 0,
          "decline_redirect_uri": "https://signnow.com",
          "prefill_signature_name": "Buyer signature"
        }
      ]
    },
    {
      "order": 2,
      "invite_emails": [
        {
          "email": "seller@email.com",
          "message": "Please contact for any questions",
          "subject": "Review and sign documents",
          "reminder": {
            "remind_after": 3,
            "remind_before": 5,
            "remind_repeat": 7
          },
          "expiration_days": 30
        }
      ],
      "invite_actions": [
        {
          "email": "seller@email.com",
          "action": "sign",
          "role_name": "Seller",
          "document_id": "XXXXX56dc7d3430ba89514667ce4f32da7b33f76",
          "redirect_uri": "https://example.com",
          "allow_reassign": "0",
          "authentication": {
            "type": "password",
            "value": "1233456"
          },
          "i_am_recipient": false,
          "redirect_target": "blank",
          "allow_forwarding": false,
          "close_redirect_uri": "https://close-redirect-uri.com",
          "show_decline_button": true,
          "decline_by_signature": "0",
          "decline_redirect_uri": "https://signnow.com",
          "prefill_signature_name": "Seller signature"
        }
      ]
    },
    {
      "order": 3,
      "invite_emails": [
        {
          "email": "approver@email.com",
          "message": "Please contact for any questions",
          "subject": "Review and approve documents",
          "expiration_days": 30
        }
      ],
      "invite_actions": [
        {
          "email": "approver@email.com",
          "action": "approve",
          "role_name": "Approver",
          "document_id": "XXXXX56dc7d3430ba89514667ce4f32da7b33f76",
          "redirect_uri": "https://www.signnow.com/",
          "authentication": {
            "type": "password",
            "value": "1233456"
          }
        },
        {
          "email": "approver@email.com",
          "action": "approve",
          "role_name": "Approver",
          "document_id": "YYYYY7a5dc3d47c4ba574a86b573a0562a07cc77",
          "redirect_uri": "https://www.signnow.com/",
          "authentication": {
            "type": "password",
            "value": "1233456"
          }
        }
      ]
    },
    {
      "order": 4,
      "invite_emails": [
        {
          "email": "viewer@email.com",
          "message": "Please contact for any questions",
          "subject": "Review documents"
        }
      ],
      "invite_actions": [
        {
          "email": "viewer@email.com",
          "action": "view",
          "role_name": "Viewer",
          "document_id": "XXXXX56dc7d3430ba89514667ce4f32da7b33f76"
        }
      ]
    }
  ],
  "sign_as_merged": true,
  "general_reminder": {
    "remind_after": 3,
    "remind_before": 5,
    "remind_repeat": 7
  },
  "completion_emails": [],
  "general_expiration_days": 30
}
```

## Responses

### 200

Document group invite created.

**Example** (`example-1`)

```json
{
  "id": "5e7d9934e1f544d187ba2fde985594342933d9d2",
  "pending_invite_link": null
}
```

**Example** (`application/json`)

```json
{
  "id": "5e7d9934e1f544d187ba2fde985594342933d9d2",
  "pending_invite_link": null
}
```

### 400

* `invite_actions` consists of more than one action with the same `email_group` and the same `document_id`.
* `role` not found.
* `group_id` not found.
* Invite already exists.

**Validation errors**:

* `language` is not a string.
* Incorrect `language`.
* One recipient must have the same `language`.
* `redirect_uri` is not a string.
* Empty `redirect_uri`.
* `redirect_uri` is not a correct URL.
* `redirect_uri` is longer than 2048 characters.
* One recipient must have the same `redirect_uri`.
* `decline_redirect_uri` is not a string.
* Empty `decline_redirect_uri`.
* `decline_redirect_uri` is not a correct URL.
* `decline_redirect_uri` is longer than 2048 characters.
* `decline_redirect_uri` cannot be used with the `view`.
* One recipient must have the same `decline_redirect_uri`.
* `close_redirect_uri` is not a string.
* Empty `close_redirect_uri`.
* `close_redirect_uri` is not a correct URL address
* `close_redirect_uri` is longer than 2048 characters.
*  One recipient must have the same `close_redirect_uri`.
* `redirect_target` is not a string.
* Incorrect `redirect_target`. Allowed values: `self`, `blank`.
* One of redirect URLs is required if `redirect_target` is added.
* One recipient must have the same `redirect_target`.
* `invite_emails` contains both `email` and `email_group` (must contain only one of these).
* `allow_reassign` is not allowed for an email group.
* Incorrect format of `email_groups`.
* Email group `id` or email group `name` is missing.
* Email group `id` is not a string.
* Email group `id` is not a correct unique id.
* Email group `name` is not a string.
* Email group `name` contains forbidden characters (4-byte characters, such as emojis).
* Emails in `email_groups` are missing.
* Emails in `email_groups` is not an array of arrays.
* Emails in `email_groups` contains more than 15 emails.
* Emails in an email group must be unique.
* Email in `email_groups.emails` is not a string.
* Email in `email_groups.emails` is not a correct email address.
* `signature.type` is missing.
* Incorrect `signature.type`. Allowed values: `eideasy`,`eideasy-pdf`, `nom151`.
* Missing or different QES settings for one or more signers.
* 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.

**SMS invite (`phone_invite`) errors**:

* `phone_invite` type incorrect.
* `phone_invite` empty.
* `phone_invite` too long.
* `phone_invite` format incorrect.
* `phone_invite` in `invite_sms` type is incorrect.
* `phone_invite` in `invite_sms` is empty.
* `phone_invite` in `invite_sms` is too long.
* `phone_invite` in `invite_sms` format is incorrect.
* `expiration_days` in `invite_sms` type incorrect.
* `expiration_days` in `invite_sms` range incorrect.
* `remind_after` range incorrect.
* `remind_before` range incorrect.
* `remind_repeat` range incorrect.
* `phone_invite` with CFR org setting enabled.
* `phone_invite` with consent org setting enabled.
* `phone_invite` with `require_login` setting enabled.
* Incorrect phone number.
* `allow_reassign` not allowed for `phone_invite`.

**Example** (`role not found`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Role Signer 1 on document edXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX was not specified in any invite_actions. All roles must be used in all document groups"
    }
  ]
}
```

**Example** (`Email not string`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `email` in `email_groups.emails` should be of type string."
    }
  ]
}
```

**Example** (`Empty redirect_uri`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "Field `redirect_uri` must not be an empty string."
    }
  ]
}
```

**Example** (`Incorrect language`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `language` field is invalid, allowed values: \"en\", \"es\", \"fr\"."
    }
  ]
}
```

**Example** (`group_id not found`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "unable to find document group"
    }
  ]
}
```

**Example** (`phone_invite empty`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `phone_invite` must not be empty string."
    }
  ]
}
```

**Example** (`CFR org restriction`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The phone_invite cannot be used with the CFR setting enabled."
    }
  ]
}
```

**Example** (`consent restriction`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The phone_invite cannot be used with the consent setting enabled."
    }
  ]
}
```

**Example** (`language not string`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `language` field must be a string."
    }
  ]
}
```

**Example** (`Missing redirect URL`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The one of `redirect_uri` fields is required when `redirect_target` is added."
    }
  ]
}
```

**Example** (`Invite already exists`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "An group invite already exists for this document group."
    }
  ]
}
```

**Example** (`phone_invite too long`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `phone_invite` value is too long. It should have 14 characters."
    }
  ]
}
```

**Example** (`redirect_uri too long`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `redirect_uri` field must contain no more than 2048 characters."
    }
  ]
}
```

**Example** (`Duplicate viewer email`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Two viewer actions in one order should not have one user email for document"
    }
  ]
}
```

**Example** (`Incorrect phone number`)

```json
{
  "errors": [
    {
      "code": 104833,
      "message": "The phone_invite value holds a non-existent phone number."
    }
  ]
}
```

**Example** (`Missing email group id`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `id` in `email_groups` should not be blank."
    }
  ]
}
```

**Example** (`Missing signature.type`)

```json
{
  "code": 66390,
  "message": "Signature type could not be blank"
}
```

**Example** (`redirect_uri not a URL`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "Field `redirect_uri` must be a valid URL."
    }
  ]
}
```

**Example** (`Unmatching redirect_uri`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `redirect_uri` must be equal for the same signer."
    }
  ]
}
```

**Example** (`redirect_uri not string`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "Field `redirect_uri` must be of type string."
    }
  ]
}
```

**Example** (`Empty close_redirect_uri`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `close_redirect_uri` field must not be empty."
    }
  ]
}
```

**Example** (`Incorrect signature.type`)

```json
{
  "code": 66390,
  "message": "The signature_type must be one of the following types: eideasy, eideasy-pdf, nom151"
}
```

**Example** (`Incorrect email_groups.id`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `id` in `email_groups` should be a valid unique id."
    }
  ]
}
```

**Example** (`Incorrect redirect_target`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `redirect_target` field is invalid, allowed values: self, blank."
    }
  ]
}
```

**Example** (`Missing email_groups.name`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `name` in `email_groups` should not be blank."
    }
  ]
}
```

**Example** (`Missing emails in a group`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `emails` in `email_groups` should not be blank."
    }
  ]
}
```

**Example** (`require_login restriction`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The phone_invite cannot be used with the require_login_for_signing setting enabled."
    }
  ]
}
```

**Example** (`Empty decline_redirect_uri`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `decline_redirect_uri` field must not be empty."
    }
  ]
}
```

**Example** (`Too many emails in a group`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Email group cannot contain more than 15 emails."
    }
  ]
}
```

**Example** (`Unmatching redirect_target`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `redirect_target` fields must be the same for the one signer."
    }
  ]
}
```

**Example** (`email not an email address`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `email` in `email_groups.emails` should be a valid email address."
    }
  ]
}
```

**Example** (`email_groups.id not string`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `id` in `email_groups` should be of type string."
    }
  ]
}
```

**Example** (`redirect_target not string`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `redirect_target` field must be a string."
    }
  ]
}
```

**Example** (`Duplicate emails in a group`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Email in email group should be unique."
    }
  ]
}
```

**Example** (`close_redirect_uri too long`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `close_redirect_uri` field must contain no more than 2048 characters."
    }
  ]
}
```

**Example** (`emails not array of arrays.`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `emails` in `email_groups` must be an array of arrays."
    }
  ]
}
```

**Example** (`phone_invite type incorrect`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `phone_invite` value should be of type string."
    }
  ]
}
```

**Example** (`close_redirect_uri not a URL`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `close_redirect_uri` field contains a URL in an invalid format."
    }
  ]
}
```

**Example** (`email_groups.name not string`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field `name` in `email_groups` should be of type string."
    }
  ]
}
```

**Example** (`remind_after range incorrect`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The remind_after attribute cannot be less than 0"
    }
  ]
}
```

**Example** (`Unmatching close_redirect_uri`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `close_redirect_uri` fields must be the same for the one signer."
    }
  ]
}
```

**Example** (`close_redirect_uri not string`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `close_redirect_uri` field must be a string."
    }
  ]
}
```

**Example** (`decline_redirect_uri too long`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `decline_redirect_uri` field must contain no more than 2048 characters."
    }
  ]
}
```

**Example** (`phone_invite format incorrect`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `phone_invite` value is incorrect."
    }
  ]
}
```

**Example** (`remind_before range incorrect`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The remind_before attribute cannot be less than 0"
    }
  ]
}
```

**Example** (`remind_repeat range incorrect`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The remind_repeat attribute cannot be less than 0"
    }
  ]
}
```

**Example** (`decline_redirect_uri not a URL`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `decline_redirect_uri` field contains a URL in an invalid format."
    }
  ]
}
```

**Example** (`Both email and email_group used`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The `email` or `email_group.name` in `invite_emails` is required. But you cannot use 2 parameters at one time."
    }
  ]
}
```

**Example** (`Unmatching decline_redirect_uri`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `decline_redirect_uri` fields must be the same for the one signer."
    }
  ]
}
```

**Example** (`decline_redirect_uri for viewer`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `decline_redirect_uri` field can be used with `sign` action only."
    }
  ]
}
```

**Example** (`decline_redirect_uri not string`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `decline_redirect_uri` field must be a string."
    }
  ]
}
```

**Example** (`prefill_signature_name is empty`)

```json
{
  "errors": [
    {
      "code": 19021121,
      "message": "The `prefill_signature_name` field cannot be empty."
    }
  ]
}
```

**Example** (`prefill_signature_name too long`)

```json
{
  "errors": [
    {
      "code": 19021120,
      "message": "The `prefill_signature_name` field cannot exceed 255 characters."
    }
  ]
}
```

**Example** (`One user has different languages`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `language` fields must be the same for the one user."
    }
  ]
}
```

**Example** (`email_groups not array of arrays`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "email_groups must be an array of arrays."
    }
  ]
}
```

**Example** (`phone_invite in invite_sms empty`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `phone_invite` in invite_sms must not be empty string."
    }
  ]
}
```

**Example** (`4-byte chars in email_groups.name`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Invalid characters provided for `name` in `email_groups`."
    }
  ]
}
```

**Example** (`Missing or different QES settings`)

```json
{
  "code": 65582,
  "message": "Invalid advanced sign provider for sender organization"
}
```

**Example** (`phone_invite in invite_sms too long`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `phone_invite` value in invite_sms is too long. It should have 14 characters."
    }
  ]
}
```

**Example** (`prefill_signature_name not a string`)

```json
{
  "errors": [
    {
      "code": 19021118,
      "message": "The `prefill_signature_name` field must be a string."
    }
  ]
}
```

**Example** (`allow_reassign used with email group`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Could not set the allow_reassign parameter for a signing group."
    }
  ]
}
```

**Example** (`phone_invite in invite_sms incorrect`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `phone_invite` value in invite_sms is incorrect."
    }
  ]
}
```

**Example** (`reassign not allowed for phone_invite`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The `allow_reassign` in invite_actions could not be presented for phone_invite"
    }
  ]
}
```

**Example** (`phone_invite type in invite_sms incorrect`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `phone_invite` value in invite_sms should be of type string."
    }
  ]
}
```

**Example** (`expiration_days in invite_sms type incorrect`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `expiration_days` in invite_sms must be integer"
    }
  ]
}
```

**Example** (`expiration_days in invite_sms range incorrect`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The `expiration_days` in invite_sms should be between 3 and 180."
    }
  ]
}
```

**Example** (`prefill_signature_name contains 4-byte characters`)

```json
{
  "errors": [
    {
      "code": 19021119,
      "message": "UTF 4-byte characters are not supported in the `prefill_signature_name` field."
    }
  ]
}
```

### 401

Incorrect or missing bearer token.

**Example** (`Example 1`)

```json
{
  "code": 1537,
  "error": "invalid_token"
}
```

**Example** (`Unauthorized`)

```json
{
  "code": 1537,
  "error": "invalid_token"
}
```

## Code Examples

> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.

### cURL

```bash
curl -X POST \
  "https://api.signnow.com/documentgroup/{document_group_id}/groupinvite" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invite_steps": [{"order": 1, "invite_actions": [{"email": "signer1@email.com", "action": "sign", "role_name": "Signer 1", "signature": {"type": "eideasy"}, "document_id": "6e9580fa76ba4edca18fa6e680a36d10a6bab503"}]}, {"order": 2, "invite_actions": [{"email": "signer2@email.com", "action": "sign", "role_name": "Signer 2", "signature": {"type": "eideasy"}, "document_id": "c4aff212145b40888cd75e3c73c978484258c043"}]}]}'
```

---
*Full reference: https://docs.signnow.com/docs/doc-group-field-invite/operations/invite-to-sign-document-group*