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 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}}. 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:

<details> <summary><b>Recipient authentication for the signing session</b></summary>

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.

"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.

"authentication": {
    "type": "phone",
    "method": "phone_call",
    "phone": "+1XXXXXXXXX"
}

• Authentication type: password This method is used to authenticate the signer using a pre-set password.

"authentication": {
    "type": "password",
    "password": "123456"
}

</details> <br> <details> <summary><b>name_formula</b> parameter</summary>

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.

</details> <br> <details> <summary><b>auth_method</b> used in the integrated application</summary>

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.

</details> <br> <details> <summary><b>from_email, from_name</b></summary>

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.

</details> <br>

Learn more about embedded signing.

{
  "invites": [
    {
      "role": "Recipient 1",
      "email": "signer@email.com",
      "order": 1,
      "message": "Please review the invoice and sign it at your earliest convenience.",
      "subject": "Review and sign the invoice",
      "language": "en",
      "last_name": "Doe",
      "signature": {
        "type": "eideasy"
      },
      "first_name": "John",
      "auth_method": "none",
      "redirect_uri": "https://example.com",
      "authentication": {
        "type": "phone",
        "phone": "+1XXXXXXXXX",
        "method": "sms",
        "password": "123456",
        "sms_message": "Enter the password {password} to unlock your document."
      },
      "close_redirect_uri": "https://example.com",
      "decline_redirect_uri": "https://example.com",
      "prefill_signature_name": "John Doe",
      "required_preset_signature_name": "Jane Smith"
    }
  ],
  "approvers": [
    {
      "role": "Approver 1",
      "email": "approver@email.com",
      "order": 2,
      "message": "Please review the invoice and approve it at your earliest convenience.",
      "subject": "Review and approve the invoice",
      "language": "en",
      "last_name": "Doe",
      "first_name": "John",
      "auth_method": "none",
      "authentication": {
        "type": "phone",
        "phone": "+1XXXXXXXXX",
        "method": "sms",
        "password": "123456",
        "sms_message": "Enter the password {password} to unlock your document."
      }
    }
  ],
  "from_name": "Jane Doe",
  "from_email": "sender@email.com",
  "name_formula": "Contract|signer_name|signed_date"
}