--- title: "Create embedded invite" method: POST path: "/v2/documents/{document_id}/embedded-invites" --- # Create embedded invite `POST /v2/documents/{document_id}/embedded-invites` ## Request - Base URL: `https://api.signnow.com` - URL: `https://api.signnow.com/v2/documents/{document_id}/embedded-invites` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) This endpoint allows API users to create an embedded signing invite for a document. Once the invite is created, generate an embedded signing link using [`POST v2/documents/{{document_id}}/embedded-invites/{{embedded_invite_id}}/link`](/docs/document-embedded-signing/operations/generate-link-for-embedded-invite) with the ID you got in the response. Before sending your request, ensure the following: - You are the owner of the document to be signed. - The invite is being created for a document (not a template). - Your document contains fields. - The document is not part of any other invite (pending or signed). - Signers' email addresses are unique and do not exceed 150 characters. - All roles or role IDs in the document are included in the invite (specifying extra roles will result in an error). - The document owner cannot be assigned as a signer. You can also include `approvers`. These recipients review the document without signing or filling fields. Each approver requires `email`, `role`, `order`, and `auth_method`. Note that `order` values must be unique across `invites` and `approvers`. Parameters `role` and `role_id` can be retrieved from the response from [`GET /document/{{document_id}}`](/docs/document/operations/get-document). Specify a role either by `role` (unique role name, e.g. “Signer 1”), `role_id` (unique role identifier), or both `role` and `role_id`. Ensure they correspond to each other. Use these parameters to customize the request:
Recipient authentication for the signing session Use the `authentication` object to set up the signer's authentication for the signing session. * Authentication type: `phone`, method: `sms`. Note that `sms_message` parameter must contain `{password}` placeholder. This method is used to authenticate the signer using a password sent via SMS. ```json "authentication": { "type": "phone", "method": "sms", "phone": "+1XXXXXXXXX", "sms_message": "Custom test message with {password}" } ``` * Authentication type: `phone`, method: `phone_call` This method is used to authenticate the signer with a password delivered via a phone call. ```json "authentication": { "type": "phone", "method": "phone_call", "phone": "+1XXXXXXXXX" } ``` * Authentication type: `password` This method is used to authenticate the signer using a pre-set password. ```json "authentication": { "type": "password", "password": "123456" } ```

name_formula parameter Use the `name_formula` parameter to generate a completed document name based on the `text_prefix` (can be any text) and fillable field data. For example, let's set the first part of the completed document name as `Contract` and use data from two document fields (we can use up to five fields): * `signer_name` (filled as `John Smith`) * `signed_date` (filled as `20.01.2023`) After the signer completes the document, the document will have the name `Contract John Smith 20.01.2023`. Note that you can not use signature fields for `name_formula`.

auth_method used in the integrated application The `auth_method` parameter is defined by the application owner to specify the method used to authenticate the signer within the integrated application. Possible values are: `password`, `email`, `social`, `mfa`, `biometric`, `other`, `none`. **Note**: The `auth_method` parameter does not influence the signer's authentication method during the signing session. Use the `authentication` object to configure authentication for the signing session.

from_email, from_name Use `from_email` and `from_name` parameters to customize the appearance of the sender's email address and name. Note that both parameters are optional and applicable only when `delivery_type`=`email`. Explore the three scenarios of passing the from_name and from_email parameters: **When both `from_email` and `from_name` are passed:** The custom `from_name` appears: - in email subject of the invite, reassign, reminder, and completed emails. The custom `from_email` appears: - in email body of the invite, reassign, reminder, and completed emails. - when clicking **Contact Sender** and in **Reply-to** in the emails. - in the signing session: when clicking **Contact Sender** in the **More Actions** menu. --- **When only `from_email` is passed:** The local part of `from_email` (before `@`) appears: - in email subject of the invite, reassign, reminder, and completed emails. The custom `from_email` appears: - in email body of the invite, reassign, reminder, and completed emails. - when clicking **Contact Sender** and in **Reply-to** in the emails. - in the signing session: when clicking **Contact Sender** in the **More Actions** menu. --- **When only `from_name` is passed:** The custom `from_name` appears: - in email subject of the invite, reassign, reminder, and completed emails. The default (owner’s) `from_email` appears: - in email body of the invite, reassign, reminder, and completed emails. - when clicking **Contact Sender** and in **Reply-to** in the emails. - in the signing session: when clicking **Contact Sender** in the **More Actions** menu.

Learn more about [embedded signing](/docs/guides-embedded-signing). ## Request body - object - `invites` object[]: The object that holds the attributes of the invite. - `role` string: Recipient's role name. - `email` string, required: Email address of the recipient. - `order` integer, required: The order of signing. - `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. - `last_name` string: Signer'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 vaules are `eideasy`, `nom151`. For more information, see [QES user guide](/docs/qualified-electronic-signature). - `first_name` string: Signer'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. - `authentication` object: Authentication settings used to verify the recipient 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`. - `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. - `link_expiration ` integer: In how many minutes the email invite expires. Can be used only if `delivery_type`=`email`. - `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. - `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`. - `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 signer. - `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. Can not be used simultaneously with `prefill_signature_name` or `force_new_signature` for the same role. - `approvers` object[]: The object that holds the attributes of the approver. Approvers review the document but do not sign or fill in fields. `order` values must be unique across `invites` and `approvers`. - `role` string, required: Approver's role name. Must be unique within `approvers`. - `email` string, required: Email address of the approver. - `order` integer, required: The order of approval. Each `order` value in `approvers` must be unique within the array and must not be shared with signer roles. - `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 approval session for the approver. Possible values: `en` for English, `es` for Spanish, `fr` for French. - `last_name` string: Approver's last name. - `first_name` string: Approver's first name. - `auth_method` string, required: Defines the method used to authenticate the approver within the integrated application. Allowed values: `password`, `email`, `mfa`, `biometric`, `social`, `other`, `none`. - `delivery_type` string: Defines how the invite is sent. Allowed values: `email`, `link`. - `authentication` object: Authentication settings used to verify the approver identity. - `type` string: Authentication type used for the approver authentication during the approval session. Required inside `authentication` object. Allowed values: `phone`, `password`. - `phone` string: Phone number used to authenticate the approver. 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 approver authentication. Required inside the `authentication` object with the `password` authentication type. - `sms_message` string: Custom SMS message sent to the approver, containing the {password} placeholder. Used with the `sms` method. - `link_expiration` integer: In how many minutes the email invite expires. Can be used only if `delivery_type`=`email`. - `session_expiration` integer: In how many minutes the approval session expires. If a link is generated for this invite, the session expiration is reset. Can be used only if `delivery_type=email`. - `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`. - `name_formula` string: Used to generate a completed document name based on `text_prefix` (can be any text) and field data (excluding signature fields). You can use up to 5 fields. ## Response `201` Successful response. Returns the created embedded invites, one per signer. Depending on the request settings, an invite can also include the signing `link`, its expiration time, and redirect settings. - object - `data` object[]: Data object with the embedded invite info. - `id` string: ID of the created embedded invite. - `link` string: Embedded signing link. Returned only for some invite settings. - `email` string: Email address of the signer. - `order` integer: Position of the signer in the signing order. - `status` string: Status of the embedded invite. `pending` for a new invite. - `role_id` string: ID of the signer role. - `expires_at` integer: Unix timestamp of when the embedded signing link expires. Returned together with `link`. - `redirect_uri` string: URL the signer is redirected to after signing. Returned only for some invite settings. - `redirect_target` string: Where the redirect URL opens: `self` or `blank`. Returned only for some invite settings. - `decline_redirect_uri` string: URL the signer is redirected to after declining the document. Returned only for some invite settings. ## Other responses - `400`: * Document has active invites. * Email addresses in embedded invites are not unique. * Document has no active fields. * The role doesn't exist in the document. * Document owner's email was used as a signer's email. * Not all of the document roles were used. * Invite for the role already exists. **Validation errors**: * The `prefill_signature_name` contains unsupported characters. * The `authentication.type` is not a string. * The `authentication.type` is not valid. Possible values: `phone`, `password`. * The `phone` is not a string. * The `phone` format is not valid. * The `phone` field is required when `authentication.type` = `phone`. * The `method` is not valid. Possible values: `sms`, `phone_call`. * The`method` parameter can be used if `authentication.type` = `phone`. * The `password` is not a string. * The `password` parameter is required when `authentication.type` = `password`. * The `sms_message` is not a string. * The `sms_message` value is empty. * The `sms_message` value is too long (must have 154 characters or less). * The `sms_message` contains unsupported characters. * The `phone` parameter is required when `authentication.type` = `phone`. * The `method` parameter is required when `authentication.type` = `phone`. * The `sms_message` parameter can be used only when `authentication.type` = `phone` and `method` = `sms`. * The `password` field is required when `authentication.type` = `password`. * The `method` field is not a string. * The `authentication.type` is empty. * The `name_formula` field is not a string. * The `name_formula` value is empty. * The `name_formula` contains unsupported characters. * The `name_formula` contains more than 5 fields. * The `name_formula` have `{field_name}` that does not exist in document or field type is not text. * The `name_formula` have duplicate `{field_name}` values. * The `required_preset_signature_name` is not a string. * The `required_preset_signature_name` value is empty. * The `required_preset_signature_name` is too long (must not exceed 255 characters). * The `required_preset_signature_name` contains unsupported characters. * Parameter `required_preset_signature_name` is used with `prefill_signature_name` for the same role. * Parameter `required_preset_signature_name` is used with `force_new_signature` for the same role. * The `language` is not a string. * The`language` is incorrect. Possible values: `en`, `fr`, `es`. * The `decline_redirect_uri` is not a string. * The `decline_redirect_uri` is empty. * The`decline_redirect_uri` is not a correct URL. * The`redirect_target` is not a string. * The`redirect_target` is incorrect. Possible values: self, blank. * One of `redirect_uri` fields is required when `redirect_target` is added. * The `redirect_uri` is too long (must not exceed 2048 characters). * The `decline_redirect_uri` is too long (must not exceed 2048 characters). * The `delivery_type` is not a string. * Incorrect `delivery_type`. Possible values: `email`, `link`. * The `link_expiration` is not an integer. * The `link_expiration` is incorrect (must be 15 or more). * The `link_expiration` is incorrect (must be 45 or less). * The `link_expiration` can only be used if `delivery_type=email`. * The `session_expiration` is not an integer. * The `session_expiration` is out of range. * The `session_expiration` can only be used if `delivery_type=email`. * Parameter `subject` in `invites` is not a string. * Parameter `subject` in `invites` is empty. * Parameter `subject` in `invites` contains unsupported characters. * Parameter `subject` in `invites` is too long. * Parameter `subject` in `invites` is used when `delivery_type` is not `email`. * Parameter `message` in `invites` is not a string. * Parameter `message` in `invites` is empty. * Parameter `message` in `invites` contains unsupported characters. * Parameter `message` in `invites` is too long. * Parameter `message` in `invites` is used when `delivery_type` is not `email`. * Your subscription plan does not include email invite customization. **QES-specific errors**: * The organization has no advanced sign provider enabled. * The user is not part of the organization. * Multiple signers were found in a single step. * Different signature providers assigned to signers. * The `signature` field type is incorrect. * The `signature.type` value is empty. * The `signature.type` value type is incorrect. * The `signature.type` value is not supported. **Approver-specific errors**: * The `approvers` field is not an array. * The `approvers` field items are not arrays. * In `approvers`, multiple approvers share the same `order`. * An approver's `order` is shared with another role. * In `approvers`, role names are not unique. * The `email` field in `approvers` is not a string / is blank / is not a valid email. * The `role` field in `approvers` is not a string / is blank / exceeds 255 characters / contains 4-byte characters. * The `order` field in `approvers` is not an integer / is blank / is not between 1 and 127. * The `auth_method` field in `approvers` is not a string / is blank / is not one of the allowed values. * The `first_name` field in `approvers` is not a string / contains 4-byte characters / exceeds the character limit. * The `last_name` field in `approvers` is not a string / contains 4-byte characters / exceeds the character limit. * The `language` field in `approvers` is not a string / is wrong (allowed: `en`, `fr`, `es`). * The `delivery_type` field in `approvers` is not a string / is wrong (allowed: `email`, `link`). * The `link_expiration` field in `approvers` is not an integer / is less than 15 minutes / is set when `delivery_type` is not `email`. * The `session_expiration` field in `approvers` is not an integer / is out of range / is set when `delivery_type` is not `email`. * The `subject` field in `approvers` is not a string / is blank / contains 4-byte characters / exceeds the character limit / is set when `delivery_type` is not `email`. * The `message` field in `approvers` is not a string / is blank / contains 4-byte characters / exceeds the character limit / is set when `delivery_type` is not `email`. * Custom authentication `sms_message` without a paid API plan, an API free trial, or a Site License. - `403`: User doesn't own the document. - `404`: Document not found. - `422`: The document is a template. --- [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)