--- title: "Invite to sign via SMS" url: "https://docs.signnow.com/docs/document-field-invite/operations/post-document-document-id-for-sms-invite-send-invite-via-sms" type: "endpoint" section: "document-field-invite" slug: "document-field-invite/operations/post-document-document-id-for-sms-invite-send-invite-via-sms" method: "POST" path: "/document/{doc_id_for_sms}/invite" operation_id: "post-document-document-id-for-sms-invite-send-invite-via-sms" authorization: "bearer" --- # Invite to sign via SMS `POST /document/{doc_id_for_sms}/invite` This endpoint allows users to send a document for signature via SMS. Recipients receive an SMS with a link to the document. It is the same `POST /document/{document_id}/invite` request as [Invite to sign](/docs/document-field-invite/operations/post-document-doc-id-invite), with signers identified by `phone_invite`. Different signers of one invite can receive it by SMS or by email. Learn more about [SMS invites](/docs/sms-invite). **Notes** * SMS delivery is available for signers in the `to` array. Viewers and approvers receive the invite by email. * Identify each signer by exactly one of `phone_invite`, `email`, or `email_group`. * Use `sms_message` to customize the SMS text. `subject`, `message`, and `header` in `to` apply only to signers invited by email. * `subject` and `message` in the request root are allowed when at least one signer receives the invite by email. * `phone_invite` is `+` followed by digits, max `14` characters. * SMS invites require the CFR and **Require login to sign** organization settings to be off, and cannot be used with `sso_login` authentication. See the errors in the `400` response. * Custom `sms_message` and `authentication_sms_message` require an API free trial, an active API subscription, or a Site License. ## Authorization bearer ## Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `doc_id_for_sms` | string | Yes | ID of the document. The same `document_id` as in [Invite to sign](/docs/document-field-invite/operations/post-document-doc-id-invite). | ## Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Content-type` | string | No | application/json | ## Request Body **Schema** ```json { "type": "object", "required": [ "from", "to" ], "properties": { "cc": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of CC recipients. Each address must be unique." }, "to": { "type": "array", "items": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "minLength": 1, "description": "Signer's role name, for example `Signer 1`. Required unless `role_id` is specified." }, "email": { "type": "string", "minLength": 1, "description": "Signer's email address for an email invite. Use exactly one of `email`, `phone_invite`, or `email_group` per signer." }, "order": { "type": "integer", "description": "Order of signing: `1` - the signer signs the document first, then the document is sent to `2`, `3`, and so on. Several signers can have the same order. Min: `1`, Max: `127`." }, "phone": { "type": "string", "example": "+1XXXXXXXXXX", "description": "Phone number used to verify the signer. Required with `\"authentication_type\": \"phone\"`." }, "header": { "type": "string" }, "method": { "type": "string", "default": "sms", "description": "Method of the `phone` authentication type. Required with `\"authentication_type\": \"phone\"`. Possible values: `sms`, `phone_call`." }, "message": { "type": "string", "minLength": 1, "description": "Custom email message for the signer. Not allowed for signers invited by SMS. Requires a paid API plan, an API free trial, or a Site License." }, "role_id": { "type": "string", "minLength": 1, "description": "ID of the signer's role. Can be used instead of `role`." }, "subject": { "type": "string", "minLength": 1, "description": "Custom email subject for the signer. Not allowed for signers invited by SMS. Requires a paid API plan, an API free trial, or a Site License." }, "language": { "type": "string", "description": "Language of the signing session and notification emails for the signer. Possible values: `en`, `es`, `fr`. If not set, the language of your SignNow account is used. If emails are branded, you can set up [your own](/docs/guides-branding#language-branding) email texts in different languages." }, "password": { "type": "string", "description": "Password used to verify the signer. Required with `\"authentication_type\": \"password\"`." }, "reassign": { "type": "string", "default": "0", "description": "Specifies whether the signer can forward the invite to another email address. `0` - signer cannot forward the invite, `1` - signer can forward the invite. Cannot be used with `email_group`." }, "reminder": { "type": "object", "properties": { "remind_after": { "type": "integer", "description": "Days after the invite is sent before a reminder is delivered. Must be less than `expiration_days`." }, "remind_before": { "type": "integer", "description": "Days before expiration when a reminder is delivered. Must be less than `expiration_days`." }, "remind_repeat": { "type": "integer", "description": "Days between repeated reminders." } }, "description": "Reminder settings for the signer." }, "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." } }, "description": "This object is used to request QES signatures from signers. To use it, a user must be a member of an organization 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)." }, "email_group": { "type": "object", "properties": { "name": { "type": "string", "description": "A name of the email group. Must be defined in the `email_groups` array." } }, "description": "A group of users that should receive the invite. When one of the users signs the document, the document is completed. Must be used with the `email_groups` array. Use exactly one of `email`, `phone_invite`, or `email_group` per signer. Cannot be used with `reassign`." }, "sms_message": { "type": "string", "example": "Hi, here is a document for signature from {sender_email}", "description": "Custom text of the SMS invite, max `230` characters. Only GSM-7 characters are allowed. Supports the `{sender_email}` placeholder, which is replaced with the sender's email address. The link to the document and an opt-out notice are added at the end of the SMS automatically. Without this parameter, the signer receives the default message: \"{sender_email} has sent you a document. Follow the link to view the document\". Used only for signers invited by SMS. Requires an API free trial, an active API subscription, or a Site License." }, "phone_invite": { "type": "string", "example": "+1XXXXXXXXXX", "description": "Signer's phone number for an SMS invite: `+` followed by digits, max `14` characters. Use exactly one of `email`, `phone_invite`, or `email_group` per signer. See [Invite to sign via SMS](/docs/document-field-invite/operations/post-document-document-id-for-sms-invite-send-invite-via-sms)." }, "redirect_uri": { "type": "string", "description": "When all the requested fields are completed and signed, the signer is redirected to this URI." }, "expiration_days": { "type": "integer", "default": 30, "description": "In how many days the invite expires. Min: `1`, Max: `180`. Default: `30`." }, "payment_request": { "type": "object", "description": "Payment request settings. See [Send document invite with payment request](/docs/request-payments/operations/post-document-document-id-invite)." }, "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." }, "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. " }, "authentication_type": { "type": "string", "description": "Type of signer's identity verification. Possible values: `password`, `phone`, `sn_login`, `sso_login`. `sso_login` cannot be used for signers invited by SMS." }, "force_new_signature": { "type": "number", "description": "Whether or not the signer can use their saved signature. Possible values: 0 - signer can use a saved signature, 1 - signer has to add a new signature" }, "decline_by_signature": { "type": "string", "default": "0", "description": "Specifies whether the signer can decline the invite by clicking a signature field. `0` - signer cannot decline, `1` - signer can decline." }, "decline_redirect_uri": { "type": "string", "description": "The link that opens after the signing session has been declined by the signer." }, "is_short_link_invite": { "type": "boolean" }, "signing_instructions": { "type": "string" }, "prefill_signature_name": { "type": "string", "example": "Jane Doe", "maxLength": 255, "description": "The text displayed in the Signature field. The signer can edit this value." }, "id_verification_required": { "type": "string" }, "authentication_sms_message": { "type": "string", "example": "Enter the password {password} to unlock your document.", "description": "Custom SMS message with the verification code, max `140` characters. Must contain the `{password}` placeholder. Used only with `\"method\": \"sms\"`. Without this parameter, the signer receives the default SMS: \"SignNow document invite unlock code: 123456\". Requires an API free trial, an active API subscription, or a Site License." }, "is_close_redirect_canceled": { "type": "boolean", "default": false, "description": "Specifies whether the save progress redirect setting is canceled for the organization.`true` \u2013 the redirect is canceled;`false` \u2013 the redirect remains active." }, "electronic_consent_required": { "type": "boolean" }, "is_finish_redirect_canceled": { "type": "boolean", "default": false, "description": "Specifies whether the completion redirect setting is canceled for the organization.`true` \u2013 the redirect is canceled;`false` \u2013 the redirect remains active." }, "is_decline_redirect_canceled": { "type": "boolean", "default": false, "description": "Specifies whether the decline redirect setting is canceled for the organization.`true` \u2013 the redirect is canceled;`false` \u2013 the redirect remains active." }, "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." } } }, "minItems": 1, "description": "Signers and their invite settings. Identify each signer by exactly one of `email`, `phone_invite`, or `email_group`.", "uniqueItems": true }, "from": { "type": "string", "minLength": 1, "description": "Sender's email address: you can use only the email address associated with your SignNow account (login email) as `from` address." }, "notify": { "type": "object", "properties": { "cc": { "type": "boolean" }, "owner": { "type": "boolean" } } }, "cc_step": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the step" }, "step": { "type": "integer", "description": "The order of sending, starts from `1`." }, "email": { "type": "string", "minLength": 1, "description": "CC recipient's email address." } } }, "minItems": 1, "description": "Order and settings for sending CC emails.", "uniqueItems": true }, "message": { "type": "string", "minLength": 1, "description": "Email message for all signers invited by email. Not allowed when all signers are invited by SMS. Requires a paid API plan, an API free trial, or a Site License." }, "subject": { "type": "string", "minLength": 1, "description": "Email subject for all signers invited by email. Not allowed when all signers are invited by SMS. Requires a paid API plan, an API free trial, or a Site License." }, "viewers": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "description": "Viewer's role name" }, "email": { "type": "string", "minLength": 1, "description": "Viewer's email address" }, "order": { "type": "integer", "description": "The order of sending, starts from `1`. Min: `1`, Max: `127`." }, "header": { "type": "string" }, "message": { "type": "string", "description": "Custom email message for the viewer. Requires a paid API plan, an API free trial, or a Site License." }, "subject": { "type": "string", "description": "Custom email subject for the viewer. Requires a paid API plan, an API free trial, or a Site License." }, "email_group": { "type": "object" }, "redirect_target": { "type": "string", "description": "Determines whether to open the redirect link in a new tab or in the same tab. Possible values: `blank` - new tab, `self` - same tab." }, "close_redirect_uri": { "type": "string", "example": "https://unique-solutions.com", "description": "The link that opens after the viewer clicks **Close**.", "x-stoplight": { "id": "lflmo6swpygw1" } }, "is_short_link_invite": { "type": "boolean" } } }, "minItems": 1, "description": "Recipients with read-only access to the document. Viewers receive the invite by email.", "uniqueItems": true }, "settings": { "type": "object", "properties": { "pki_enabled": { "type": "boolean" } } }, "approvers": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "Approver", "description": "Approver's role name." }, "email": { "type": "string", "example": "approver@email.com", "description": "Approver's email address." }, "order": { "type": "integer", "description": "The order of receiving the invite. Min: `1`, Max: `127`." }, "header": { "type": "string" }, "message": { "type": "string", "example": "Review and approve the invoice", "description": "Custom email message for the approver. Requires a paid API plan, an API free trial, or a Site License." }, "subject": { "type": "string", "example": "Approve the invoice", "description": "Custom email subject for the approver. Requires a paid API plan, an API free trial, or a Site License." }, "reminder": { "type": "object", "properties": { "remind_after": { "type": "integer", "description": "Days after the invite is sent before a reminder is delivered. Must be less than `expiration_days`." }, "remind_before": { "type": "integer", "description": "Days before expiration when a reminder is delivered. Must be less than `expiration_days`." }, "remind_repeat": { "type": "integer", "description": "Days between repeated reminders." } }, "description": "Reminder settings for the approver." }, "redirect_uri": { "type": "string", "example": "https://www.signnow.com/", "description": "The URL that opens after the approver approves the document." }, "authentication": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of verification. Possible values: `password`, `phone`, `sn_login`, `sso_login`." }, "phone": { "type": "string", "description": "Phone number used to verify the approver. Required with `\"type\": \"phone\"`." }, "method": { "type": "string", "description": "Method of the `phone` verification type. Required with `\"type\": \"phone\"`. Possible values: `sms`, `phone_call`." }, "password": { "type": "string", "description": "Password used to verify the approver. Required with `\"type\": \"password\"`." }, "sms_message": { "type": "string", "description": "Custom SMS message with the verification code, max `140` characters. Used with `\"method\": \"sms\"`." } }, "description": "Approver's identity verification settings." }, "expiration_days": { "type": "integer", "description": "Number of days before the invite expires. Min: `1`, Max: `180`." }, "redirect_target": { "type": "string", "example": "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." }, "is_short_link_invite": { "type": "boolean" } } }, "description": "Recipients who review and approve the document. Approvers receive the invite by email." }, "cc_message": { "type": "string", "minLength": 1, "description": "CC email message for all CC recipients" }, "cc_subject": { "type": "string", "minLength": 1, "description": "CC email subject for all CC recipients" }, "compliance": { "type": "object" }, "email_groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "An ID of an email group. A unique 40-character long ID that you need to create." }, "name": { "type": "string", "description": "A name of the group. Use it in the `to.email_group` array." }, "emails": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "An email address of the group member." } } }, "description": "Email addresses that should receive an invite. Must be unique within the group." } } }, "description": "A group of users that should receive the invite." }, "redirect_uri": { "type": "string" }, "mail_provider": { "type": "string" }, "client_timestamp": { "type": "integer" }, "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." }, "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`." } }, "x-examples": { "example-1": { "to": [ { "role": "Signer 1", "order": 1, "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "language": "en", "reassign": "0", "reminder": { "remind_after": 3, "remind_repeat": 7 }, "sms_message": "Hi, here is a document for signature from {sender_email}", "phone_invite": "+1XXXXXXXXXX", "redirect_uri": "https://example.com", "expiration_days": 30, "redirect_target": "blank", "decline_by_signature": "1" } ], "from": "sender@email.com" } } } ``` **Example** (`SMS invite`) ```json { "to": [ { "role": "Signer 1", "order": 1, "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "language": "en", "reassign": "0", "reminder": { "remind_after": 3, "remind_repeat": 7 }, "sms_message": "Hi, here is a document for signature from {sender_email}", "phone_invite": "+1XXXXXXXXXX", "redirect_uri": "https://example.com", "expiration_days": 30, "redirect_target": "blank", "decline_by_signature": "1" } ], "from": "sender@email.com" } ``` **Example** (`SMS invite with 2FA`) ```json { "to": [ { "role": "Signer 1", "order": 1, "phone": "+1XXXXXXXXXX", "method": "sms", "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "sms_message": "Hi, here is a document for signature from {sender_email}", "phone_invite": "+1XXXXXXXXXX", "authentication_type": "phone", "authentication_sms_message": "Enter the password {password} to unlock the document." }, { "role": "Signer 2", "order": 2, "role_id": "49XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "password": "123456", "phone_invite": "+1XXXXXXXXXX", "authentication_type": "password" } ], "from": "sender@email.com" } ``` **Example** (`SMS and email recipients`) ```json { "cc": [ "cc_recipient@email.com" ], "to": [ { "role": "Signer 1", "order": 1, "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "sms_message": "Hi, here is a document for signature from {sender_email}", "phone_invite": "+1XXXXXXXXXX", "expiration_days": 30 }, { "role": "Signer 2", "email": "signer2@email.com", "order": 2, "message": "Hi, this is an invite to sign a document.", "role_id": "49XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "subject": "You've got a new signature request", "expiration_days": 30 } ], "from": "sender@email.com", "message": "Please review and sign the document.", "subject": "sender@email.com needs your signature", "viewers": [ { "role": "Viewer 1", "email": "viewer@email.com", "order": 3, "message": "You've got a new document to review.", "subject": "New document" } ], "cc_message": "A document was sent for signature.", "cc_subject": "Document sent for signature" } ``` ## Responses ### 200 Returns success if the request is correct. **Example** (`example-1`) ```json { "status": "success" } ``` ### 400 Incorrect phone number All standard responses for invite: * Incorrect access token, "code": 1537. Message: "invalid_token" * Incorrect "to" email, "code": 65536. Message: "To must be a valid email." * Incorrect "from" email, "code": 65536. Message: "From must be a valid email." * Wrong role, "code": 65536. Message: "Role {{role_id_1}} does not exist on document" * The document doesn’t contain field, "code": 65594. Message: "Cannot send a field invite: This document does not contain fields." * Send the same field invite for the second time, "code": 65629. Message: "Could not create duplicate field invite" * Incorrect document, "code": 65582. Message: "Document not found" * Authentication type is missing, "code": 65536. Message: "Authentication type must not be empty" * The password or phone parameter for the authentication type is missing, "code": 65536. Message: Both password and phone must not be empty * `sms_message` value is too long, code 65536. Message : "SMS message should not exceed 230 characters". * `sms_message` value is blank , code 65536. Message : "SMS message must not be empty". * `sms_message` contains characters outside GSM-7, code 65536. Message: "Only GSM-7 characters are allowed for `sms_message`." * `phone_invite` value is not valid, code 104833. Message: "The phone_invite value is invalid." * `phone_invite` value is blank, code 104833. Message: "The phone_invite must not be empty string." * `phone_invite` value is longer than 14 characters, code 104833. Message: "The phone_invite value is too long. It should have 14 characters." * Phone number doesn't exist, code 39297. Message: "The phone_invite value holds a non-existent phone number." * Incorrect data in 'phone_invite', code 104833. Message: "The phone_invite value should be of type string." * Must be email or phone number, not both at the same time, code 65582. Message: "Either `phone_invite`, `email`, or `email_group` in `to` is required. Only one parameter at a time is allowed." * Org setting ‘Require Login to Sign’ when the setting is ON, code 46. Message: "The phone_invite cannot be used with require_login_for_signing setting enabled." * Org setting CFR is enabled, code 46. Message: "phone_invite cannot be used with cfr setting enabled." * The signer's `authentication_type` is `sso_login`, code 19099002. Message: "Authentication type sso_login is incompatible with SMS delivery type." * `subject` or `message` is set for a signer invited by SMS, code 65582. Message: "The phone_invite field is not allowed with: message, subject" * `electronic_consent_required` is `true` for a signer invited by SMS, code 65582. Message: "Electronic consent cannot be required for invite via sms" * Root `subject` or `message` is set and all signers are invited by SMS, code 65536. Message: "The phone_invite field is not allowed with subject in root when all signers via sms." or "The phone_invite field is not allowed with message in root when all signers via sms." * A viewer is identified by `phone_invite` instead of `email`, code 65536. Message: "Either `email` or `email_group` in `viewers` is required. Only one parameter at a time is allowed." * An approver is identified by `phone_invite` instead of `email`, code 65585. Message: "The `email` value should not be blank." * The custom SMS limit of a trial subscription is reached, code 46. Message: "Custom SMS limit exceeded for trial subscription." * Phone verification is used on a subscription without it, code 46. Message: "Phone authentication can't be used with the current subscription." **Example** (`SMS for a viewer`) ```json { "errors": [ { "code": 65536, "message": "Either `email` or `email_group` in `viewers` is required. Only one parameter at a time is allowed." } ] } ``` **Example** (`CFR setting enabled`) ```json { "errors": [ { "code": 46, "message": "phone_invite cannot be used with cfr setting enabled." } ] } ``` **Example** (`SMS for an approver`) ```json { "errors": [ { "code": 65585, "message": "The `email` value should not be blank." } ] } ``` **Example** (`Subject or message for an SMS signer`) ```json { "errors": [ { "code": 65582, "message": "The phone_invite field is not allowed with: message, subject" } ] } ``` **Example** (`The selected phone number is incorrect`) ```json { "errors": [ { "code": 65582, "message": "phone_invite is not valid phone for the sms sent." } ] } ``` **Example** (`Could not create duplicate field invite`) ```json { "errors": [ { "code": 65629, "message": "Could not create duplicate field invite." } ] } ``` ## Code Examples > Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running. ### cURL ```bash curl -X POST \ "https://api.signnow.com/document/{doc_id_for_sms}/invite" \ -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"to": [{"role": "Signer 1", "order": 1, "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "language": "en", "reassign": "0", "reminder": {"remind_after": 3, "remind_repeat": 7}, "sms_message": "Hi, here is a document for signature from {sender_email}", "phone_invite": "+1XXXXXXXXXX", "redirect_uri": "https://example.com", "expiration_days": 30, "redirect_target": "blank", "decline_by_signature": "1"}], "from": "sender@email.com"}' ``` --- *Full reference: https://docs.signnow.com/docs/document-field-invite/operations/post-document-document-id-for-sms-invite-send-invite-via-sms*