--- title: "Invite to sign via SMS" method: POST path: "/document/{doc_id_for_sms}/invite" --- # Invite to sign via SMS `POST /document/{doc_id_for_sms}/invite` ## Request - Base URL: `https://api.signnow.com` - URL: `https://api.signnow.com/document/{doc_id_for_sms}/invite` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Request body - object - `cc` string[]: Email addresses of CC recipients. Each address must be unique. - `to` object[], required: Signers and their invite settings. Identify each signer by exactly one of `email`, `phone_invite`, or `email_group`. - `role` string, required: Signer's role name, for example `Signer 1`. Required unless `role_id` is specified. - `email` string: Signer's email address for an email invite. Use exactly one of `email`, `phone_invite`, or `email_group` per signer. - `order` integer: 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` string: Phone number used to verify the signer. Required with `"authentication_type": "phone"`. - `header` string - `method` string: Method of the `phone` authentication type. Required with `"authentication_type": "phone"`. Possible values: `sms`, `phone_call`. - `message` string: 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` string: ID of the signer's role. Can be used instead of `role`. - `subject` string: 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` string: 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/branding-email-resources#language-branding) email texts in different languages. - `password` string: Password used to verify the signer. Required with `"authentication_type": "password"`. - `reassign` string: 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` object: Reminder settings for the signer. - `remind_after` integer: Days after the invite is sent before a reminder is delivered. Must be less than `expiration_days`. - `remind_before` integer: Days before expiration when a reminder is delivered. Must be less than `expiration_days`. - `remind_repeat` integer: Days between repeated reminders. - `signature` object: 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). - `type` string: Type of QES signature. Possible values: `eideasy`,` eideasy-pdf`, and `nom151`. All signers in the invite must have the same signature type. - `email_group` object: 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`. - `name` string: A name of the email group. Must be defined in the `email_groups` array. - `sms_message` string: 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` string: 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` string: When all the requested fields are completed and signed, the signer is redirected to this URI. - `expiration_days` integer: In how many days the invite expires. Min: `1`, Max: `180`. Default: `30`. - `payment_request` object: Payment request settings. See [Send document invite with payment request](/docs/request-payments/operations/post-document-document-id-invite). - `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. - `authentication_type` string: 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` number: 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` string: Specifies whether the signer can decline the invite by clicking a signature field. `0` - signer cannot decline, `1` - signer can decline. - `decline_redirect_uri` string: The link that opens after the signing session has been declined by the signer. - `is_short_link_invite` boolean - `signing_instructions` string - `prefill_signature_name` string: The text displayed in the Signature field. The signer can edit this value. - `id_verification_required` string - `authentication_sms_message` string: 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` boolean: Specifies whether the save progress redirect setting is canceled for the organization.`true` – the redirect is canceled;`false` – the redirect remains active. - `electronic_consent_required` boolean - `is_finish_redirect_canceled` boolean: Specifies whether the completion redirect setting is canceled for the organization.`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.`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. - `from` string, required: Sender's email address: you can use only the email address associated with your SignNow account (login email) as `from` address. - `notify` object - `cc` boolean - `owner` boolean - `cc_step` object[]: Order and settings for sending CC emails. - `name` string: Name of the step - `step` integer: The order of sending, starts from `1`. - `email` string: CC recipient's email address. - `message` string: 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` string: 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` object[]: Recipients with read-only access to the document. Viewers receive the invite by email. - `role` string: Viewer's role name - `email` string: Viewer's email address - `order` integer: The order of sending, starts from `1`. Min: `1`, Max: `127`. - `header` string - `message` string: Custom email message for the viewer. Requires a paid API plan, an API free trial, or a Site License. - `subject` string: Custom email subject for the viewer. Requires a paid API plan, an API free trial, or a Site License. - `email_group` object - `redirect_target` string: 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` string: The link that opens after the viewer clicks **Close**. - `is_short_link_invite` boolean - `settings` object - `pki_enabled` boolean - `approvers` object[]: Recipients who review and approve the document. Approvers receive the invite by email. - `role` string: Approver's role name. - `email` string: Approver's email address. - `order` integer: The order of receiving the invite. Min: `1`, Max: `127`. - `header` string - `message` string: Custom email message for the approver. Requires a paid API plan, an API free trial, or a Site License. - `subject` string: Custom email subject for the approver. Requires a paid API plan, an API free trial, or a Site License. - `reminder` object: Reminder settings for the approver. - `remind_after` integer: Days after the invite is sent before a reminder is delivered. Must be less than `expiration_days`. - `remind_before` integer: Days before expiration when a reminder is delivered. Must be less than `expiration_days`. - `remind_repeat` integer: Days between repeated reminders. - `redirect_uri` string: The URL that opens after the approver approves the document. - `authentication` object: Approver's identity verification settings. - `type` string, required: Type of verification. Possible values: `password`, `phone`, `sn_login`, `sso_login`. - `phone` string: Phone number used to verify the approver. Required with `"type": "phone"`. - `method` string: Method of the `phone` verification type. Required with `"type": "phone"`. Possible values: `sms`, `phone_call`. - `password` string: Password used to verify the approver. Required with `"type": "password"`. - `sms_message` string: Custom SMS message with the verification code, max `140` characters. Used with `"method": "sms"`. - `expiration_days` integer: Number of days before the invite expires. Min: `1`, Max: `180`. - `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. - `is_short_link_invite` boolean - `cc_message` string: CC email message for all CC recipients - `cc_subject` string: CC email subject for all CC recipients - `compliance` object - `email_groups` object[]: A group of users that should receive the invite. - `id` string: An ID of an email group. A unique 40-character long ID that you need to create. - `name` string: A name of the group. Use it in the `to.email_group` array. - `emails` object[]: Email addresses that should receive an invite. Must be unique within the group. - `email` string: An email address of the group member. - `redirect_uri` string - `mail_provider` string - `client_timestamp` integer - `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. - `general_expiration_days` integer: Default `expiration_days` applied to all recipients in the invite. Min: `1`, Max: `180`. Default: `30`. ## Response `200` Returns success if the request is correct. - object - `status` string, required: The result of the request. Returns `success` when the SMS invite is sent. ## Other responses - `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 fields, "code": 65594. Message: "Cannot send a field invite: This document does not contain fields.". * The same field invite is sent twice, "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.". * The organization setting ‘Require Login to Sign’ is on, code 46. Message: "The phone_invite cannot be used with require_login_for_signing setting enabled.". * The organization CFR setting 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.". --- [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)