--- title: "Create embedded invite" method: POST path: "/v2/document-groups/{document_group_id}/embedded-invites" --- # Create embedded invite `POST /v2/document-groups/{document_group_id}/embedded-invites` ## Request - Base URL: `https://api.signnow.com` - URL: `https://api.signnow.com/v2/document-groups/{document_group_id}/embedded-invites` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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). ## Request body - object - `invites` object[], required: Array of invite objects that includes order and settings for different recipients. - `order` integer, required: 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` object[], required: 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. - `email` string, required: Recipient's email to receive the invite. - `message` string: Invite email message. Available if the `delivery_type` = `email`. Overrides branding settings when sending emails. - `subject` string: Invite email subject. Available if the `delivery_type` = `email`. Overrides branding settings when sending emails. - `language` string: Sets the language of the signing session for the recipient. Possible values: `en` for English, `es` for Spanish, `fr` for French. - `documents` object[], required: 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. - `id` string, required: ID of the document. - `role` string, required: Recipient role in the document. - `action` string, required: Action required in the document. Allowed values: `sign`, `view`, `approve`. - `last_name` string: Recipient's last name. - `signature` object: 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. - `type` string: Type of the QES. Allowed values are `eideasy`, `nom151`. For more information, see [QES user guide](/docs/qualified-electronic-signature). - `first_name` string: Recipient's first name. - `auth_method` string, required: Defines the method used to authenticate the recipient within the integrated application. Allowed values: `password`, `email`, `mfa`, `biometric`, `social`, `other`, `none`. - `redirect_uri` string: The link that opens after the signing session has been completed. Not applicable for `approve` action. - `authentication` object: Authentication settings used to verify the recipient's identity. - `type` string: Authentication type used for the recipient authentication during the signing session. Required inside `authentication` object. Allowed values: `phone`, `password`. - `phone` string: Phone number used to authenticate the recipient. Required inside `authentication` object with the `phone` method. - `method` string: Method of the `phone` authentication type. Required inside `authentication` object with the `phone` authentication type. Allowed values: `sms`, `phone_call`. - `password` string: Password set for the recipient authentication. Required inside the `authentication` object with the `password` authentication type. - `sms_message` string: 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". - `delivery_type ` string: Defines how the invite is sent. Allowed values: `email`, `link`. - `link_expiration` integer: In how many minutes the email invite expires. Can be used only if `delivery_type`=`email`. - `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. 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` string: 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. - `session_expiration` integer: 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. - `force_new_signature` integer: 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` string: The link that opens after the signing session has been declined by the recipient. Not applicable for `approve` action. - `prefill_signature_name` string: The text displayed in the Signature field. The signer can edit this value. - `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. - `from_name` string: 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` string: 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`. ## Response `201` Returns the ID of the created invite object. - object - `data` object: Data object with the invite ID. - `id` string: ID of the created embedded invite. ## Other responses - `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. * Custom `subject` or `message` for a signer with `delivery_type` `email`, without a paid API plan, an API free trial, or a Site License. * Custom authentication `sms_message` without a paid API plan, an API free trial, or a Site License. - `403`: User doesn't own the document group. - `422`: Group invite already exists. --- [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)