--- title: "Invite to sign doc group" method: POST path: "/documentgroup/{document_group_id}/groupinvite" --- # Invite to sign doc group `POST /documentgroup/{document_group_id}/groupinvite` ## Request - Base URL: `https://api.signnow.com` - URL: `https://api.signnow.com/documentgroup/{document_group_id}/groupinvite` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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).
**Use additional attributes to customize signing experience** Parameter | Description | Example ---------|----------|--------- `reassign` | A recipient can forward the invite by clicking **More Actions** > **Forward Invite** and entering an email address. | Forward invite `force_new_signature` | A recipient must create a new signature for each signature field. | 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. | 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). | Password_authentication
## Request body - object - `cc` string[]: Array of cc email addresses. - `order_type` string: 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` object[]: 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. - `id` string, required: Signing group ID. If you created your own ID, make sure that it's 40 characters long. - `name` string, required: Signing group name - `emails` object[], required: 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. - `email` string, required: Email address in the signing group. Must be unique within a group. - `invite_steps` object[], required: Steps of the document group invite. Every step contains the `order` number, `invite_emails`, `invite_sms`, and `invite_actions` within this step. - `order` integer, required: 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` object[]: 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`. - `reminder` object: Settings for sending automatic reminders. - `remind_after` number: Number of days after sending the invite when the recipient receives a reminder SMS. Must be less than `expiration_days`. - `remind_before` number: Number of days before the invite expires when the recipient receives a reminder SMS. Must be less than `expiration_days`. - `remind_repeat` number: Number of days between each reminder sent to the recipient. - `sms_message` string: 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` string, required: Recipient's phone number for the SMS invite. Must match the `phone_invite` value of this recipient in `invite_actions`. - `expiration_days` number: Number of days before the invite expires. - `invite_emails` object[]: Objects that define custom email subject, email message, expiration and reminder settings for each recipient within a step. - `email` string, email, required: Recipient's email address - `message` string: Custom email message for the recipient. Requires a paid API plan, an API free trial, or a Site License. - `subject` string: Custom email subject for the recipient. Requires a paid API plan, an API free trial, or a Site License. - `reminder` object: Settings for sending automatic reminder emails. - `remind_after` number: x days after the invite, a recipient gets a reminder email. Must be less than `expiration_days` - `remind_before` number: x days before expiration, a recipient gets a reminder email. Must be less than `expiration_days` - `remind_repeat` number: A recipient gets a reminder email each x days after the invite is sent - `email_group` object: A contact group of recipients, for example, [CRM Contact group](/docs/contact-groups/operations/post-v2-crm-groups). - `name` string: The name of the contact group. - `expiration_days` number: In x days, the invite expires - `invite_actions` object[], required: 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. - `email` string, email: Recipient's email address. The invite is delivered by email. Identify each recipient by `email`, `phone_invite`, or `email_group` — only one of these parameters at a time. - `action` string, required: 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` string: 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/branding-email-resources#language-branding) email texts in different languages. - `role_name` string, required: 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` object: 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.
For more information, see [QES user guide](/docs/qualified-electronic-signature). - `type` string: Type of QES signature. Possible values: `eideasy`,` eideasy-pdf`, and `nom151`. All signers in the invite must have the same signature type. - `document_id` string, required: ID of the document on which actions are required from this recipient. - `email_group` object: A contact group of recipients, for example, [CRM Contact group](/docs/contact-groups/operations/post-v2-crm-groups). - `name` string: The name of the contact group. - `phone_invite` string: 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` string: The link that opens after the recipient completes the document. - `allow_reassign` string: Whether or not to allow recipients reassign this invite to another email address. Possible values: "0" - not allowed, "1" - allowed. - `authentication` object: Object that contains the type of signer's identity verification, phone number or password. - `type` string: Type of signer's identity verification. Possible values: `"password"` or `"phone"`. `phone` is available on paid plans; on a free trial or without a paid subscription, use `password`. - `phone` string: Required in case of `"type"`: `"phone"`. User's phone number. - `value` string: Required in case of `"type"`: `"password"`. The password for user authentication. - `method` string: Required in case of `"type"`: `"phone"`. Possible values: `"phone_call`", `"sms"`. - `message` string: 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. - `payment_request` object: Object that contains details about the payment request. - `type` string: In this case, must be "fixed". - `amount` string: The payment amount requested. - `currency` string: The payment currency requested. - `merchant_id` string: The ID of the merchant account added to your organization (workspace). - `redirect_target` string: 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. - `close_redirect_uri` string: The link that opens when a signer clicks **Save Progress and Finish Later** during a signing session or **Close** in view mode. Available for `sign ` action. - `decline_by_signature` string: Whether or not to allow recipients decline to sign the invite. - `decline_redirect_uri` string: The URL that opens after the recipient declines the document. Available for `sign` action. - `prefill_signature_name` string: The text displayed in the Signature field. The signer can edit this value. - `is_close_redirect_canceled` boolean: Specifies whether the save progress redirect setting is canceled for the organization (workspace).`true` – the redirect is canceled;`false` – the redirect remains active. - `is_finish_redirect_canceled` boolean: Specifies whether the completion redirect setting is canceled for the organization (workspace).`true` – the redirect is canceled;`false` – the redirect remains active. - `is_decline_redirect_canceled` boolean: Specifies whether the decline redirect setting is canceled for the organization (workspace).`true` – the redirect is canceled;`false` – the redirect remains active. - `required_preset_signature_name` string: 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. - `sign_as_merged` boolean: If true, allows API user to send an invite which opens as merged document group in a single document. - `client_timestamp` integer: The timestamp of the document group invite. - `general_reminder` object: Default `reminder` applied to all recipients in the invite. - `remind_after` integer: Days after invite is sent before a reminder is delivered. Must be less than `general_expiration_days`. - `remind_before` integer: Days before expiration when a reminder is delivered. Must be less than `general_expiration_days`. - `remind_repeat` integer: Days between repeated reminders. - `completion_emails` object[]: Object that contains email addresses and custom settings for sending emails about completing the invite. - `email` string, email: Email address of the completion email recipient. - `message` string: Custom message for the completion email. Requires a paid API plan, an API free trial, or a Site License. - `subject` string: Custom subject for the completion email. Requires a paid API plan, an API free trial, or a Site License. - `disable_document_attachment` integer: Whether to disable sending document attachments with the completion email. Possible values: 0 - enable document attachment, 1 - disable document attachment. - `general_expiration_days` integer: Default `expiration_days` applied to all recipients in the invite. Min: `1`, Max: `180`. Default: `30`. - `general_expiration_time` integer: Default expiration timestamp (Unix time, seconds) applied to all recipients in the invite. ## Response `200` Document group invite created. - object - `id` string: ID of the created document group invite. - `pending_invite_link` string: Link for signers with pending invites. ## Other responses - `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`. * Phone authentication on a free trial or without a paid subscription. - `401`: Incorrect or missing bearer token. --- [API](https://skmtc.dev/signnow/apis/signnow-api.md) - [All operations](https://skmtc.dev/signnow/apis/signnow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signnow/apis/signnow-api/revisions/1c9c30a6142b?raw)