--- 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. ## Authorization bearer ## Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `doc_id_for_sms` | string | Yes | Document ID used for SMS invite. | ## Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Content-type` | string | No | application/json | ## Request Body **Schema** ```json { "type": "object", "required": [ "from" ], "properties": { "cc": { "type": "array", "items": { "type": "string" }, "description": "Email addresses of CC recipients." }, "to": { "type": "array", "items": { "type": "object", "required": [ "phone_invite", "role", "role_id" ], "properties": { "role": { "type": "string", "example": "Recipient 1", "description": "Recipient role. Optional if the `role_id` parameter is specified." }, "order": { "type": "integer", "example": 1, "description": "Order of signing. 1 - recipient has to sign the document first, then the document is sent to 2,3 etc. Several recipients can hold the same order of signing." }, "phone": { "type": "string", "example": "+1XXXXXXXXXX", "description": "Phone number used to authenticate the signer with the `phone` authentication type.", "x-stoplight": { "id": "m443bmkxk38qp" } }, "method": { "type": "string", "example": "sms", "description": "Method of the `phone` authentication type. Allowed values: `sms`, `phone_call`." }, "role_id": { "type": "string", "example": "eeee298633c4408da11e262ac601a9e3e33f1111", "description": "Recipient role ID. Optional if the `role` parameter is specified." }, "language": { "type": "string", "example": "fr", "description": "Sets the language of the signing session for the signer. Possible values: `en` for English, `es` for Spanish, and `fr` for French. If not set, the language defaults to user's account language.", "x-stoplight": { "id": "jnm5x8n1a3zd0" } }, "password": { "type": "string", "example": "123456", "description": "Password set for the signer's authentication. Required with the `password` authentication `type`.", "x-stoplight": { "id": "e597npgqfsv3q" } }, "reassign": { "type": "string", "default": "0", "description": "Specifies whether a recipient can forward the invite to another email address. `0` - recipient cannot forward the invite. `1` - recipient can forward the invite." }, "reminder": { "type": "object", "properties": { "remind_after": { "type": "integer", "example": 10, "maximum": 179, "minimum": 1, "description": "Send the reminder email to the recipient after the set amount of days. `remind_after` must be less than `expiration_days`.", "x-stoplight": { "id": "epeykhqdtikln" } }, "remind_before": { "type": "integer", "example": 5, "maximum": 179, "minimum": 1, "description": "Send the reminder email to the recipient a set number of days before the invite expires. `remind_before` must be less than `expiration_days`.", "x-stoplight": { "id": "qa70ieiuw9zcd" } }, "remind_repeat": { "type": "integer", "example": 5, "maximum": 7, "minimum": 1, "description": "Send the reminder email to the recipient every set amount of days. `remind_repeat` must be less than `expiration_days`.", "x-stoplight": { "id": "3k11dhh882nxt" } } }, "description": "Settings for reminder notifications.", "x-stoplight": { "id": "li2wy9xdvd4t3" } }, "sms_message": { "type": "string", "example": "Hi, here is a document for signature.", "maxLength": 140, "description": "Custom text of the SMS invite, max `140` characters. Supports the `{sender_email}` placeholder that is automatically replaced with the sender's email address. The link to the document and an opt-out notice are automatically added at the end of the SMS. Without this parameter, the recipient receives the default message: \"{sender email} has sent you a document. Follow the link to view the document\". Custom SMS messages require an API free trial, an active API subscription, or a Site License." }, "phone_invite": { "type": "string", "example": "+1XXXXXXXXXX", "description": "Phone number of the recipient." }, "redirect_uri": { "type": "string", "example": "https://unique-solutions.com", "description": "The link that opens after the signer completes the signing session.", "x-stoplight": { "id": "s41v8tsllvefr" } }, "expiration_days": { "type": "integer", "example": 27, "maximum": 180, "minimum": 3, "description": "In how many days the invite expires." }, "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.", "x-stoplight": { "id": "ichhr1nqbgqq0" } }, "close_redirect_uri": { "type": "string", "example": "https://unique-solutions.com", "description": "The link that opens when a recipient clicks\u00a0**Save Progress and Finish Later**\u00a0during a signing session or\u00a0**Close**\u00a0in view mode.", "x-stoplight": { "id": "lflmo6swpygw1" } }, "authentication_type": { "type": "string", "example": "phone", "description": "Authentication type used for signer authentication during the signing session. Allowed values: `password`, `phone`.", "x-stoplight": { "id": "gbzp51s3jv7ct" } }, "decline_by_signature": { "type": "string", "default": "0", "description": "Indicates whether a recipient can select Decline to Sign when clicking the signature field. `0` - recipient cannot decline to sign, `1` - recipient can decline to sign." }, "decline_redirect_uri": { "type": "string", "example": "https://unique-solutions.com", "description": "The link that opens after the signing session has been declined by the signer.", "x-stoplight": { "id": "q6wyo8e65ie68" } }, "authentication_sms_message": { "type": "string", "example": "Enter the password {password} to unlock your document.", "maxLength": 140, "description": "Custom sms message sent to the signer, containing the {password} placeholder. Used with the `sms`authentication method. Without this parameter, the signer receives a default sms with an autogenerated password (unlock code) - \"SignNow document invite unlock code: 123456\". Customizing the 2FA SMS message requires an API free trial, an active API subscription, or a Site License.", "x-stoplight": { "id": "jej4szt5biktb" } }, "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.", "x-stoplight": { "id": "0ujli8b4stlcp" } }, "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.", "x-stoplight": { "id": "0ujli8b4stlcp" } }, "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.", "x-stoplight": { "id": "0ujli8b4stlcp" } } } } }, "from": { "type": "string", "example": "sender@email.com", "description": "Sender's email address. You can only use the email address associated with your account (login email)." }, "cc_step": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "CC 1", "description": "Name of the step." }, "step": { "type": "integer", "example": 1, "description": "The order of sending, starts from 1." }, "email": { "type": "string", "example": "cc_recipient1@email.com", "description": "CC recipient's email address." } } }, "description": "Order and settings for sending CC emails." }, "message": { "type": "string", "example": "Please review and sign the invoice", "description": "Email message for all recipients. Used when at least one receives the invite via email. Requires a paid API plan, an API free trial, or a Site License.", "x-stoplight": { "id": "1bde7qt8p99jm" } }, "subject": { "type": "string", "example": "New invoice to sign", "description": "Email subject for all recipients. Used when at least one receives the invite via email. Requires a paid API plan, an API free trial, or a Site License.", "x-stoplight": { "id": "k3d218to03izb" } }, "viewers": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "Viewer 1", "description": "Viewer's role name." }, "email": { "type": "string", "example": "viewer@email.com", "description": "Viewer's email address.\n" }, "order": { "type": "integer", "example": 1, "description": "The order of sending, starts from 1." }, "message": { "type": "string", "example": "You\u2019ve got a new document to review.", "description": "Email message for a viewer. Requires a paid API plan, an API free trial, or a Site License." }, "subject": { "type": "string", "example": "New document", "description": "Email subject for a viewer. Requires a paid API plan, an API free trial, or a Site License." }, "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." }, "close_redirect_uri": { "type": "string", "example": "https://unique-solutions.com", "description": "The link that opens after a viewer clicks the Close button." } } }, "description": "List of recipients with read-only access to the invite." }, "cc_message": { "type": "string", "example": "cc Invoice request for Signer 1", "description": "CC email message for all CC recipients." }, "cc_subject": { "type": "string", "example": "cc Invoice request", "description": "CC email subject for all CC recipients." } }, "x-examples": { "Example 1": { "cc": [ "cc_recipient1@email.com", "cc_recipient2@email.com" ], "to": [ { "role": "Signer 1", "order": 1, "method": "sms", "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "reassign": "0", "sms_message": "Hi, here is a document for signature", "phone_invite": "+1XXXXXXXXXX", "expiration_days": 27, "decline_by_signature": "1" } ], "from": "sender@some.email", "cc_step": [ { "name": "CC 1", "step": 1, "email": "cc_recipient1@email.com" }, { "name": "CC 2", "step": 2, "email": "cc_recipient2@email.com" } ], "viewers": [ { "role": "Viewer 1", "email": "viewer@email.com", "order": 1, "message": "You\u2019ve got a new document to review.", "subject": "New document", "redirect_target": "blank", "close_redirect_uri": "https://unique-solutions.com" } ], "cc_message": "cc Invoice request for Signer 1", "cc_subject": "cc Invoice request" } } } ``` **Example** (`Invite to sign via SMS`) ```json { "cc": [ "cc_recipient1@email.com", "cc_recipient2@email.com" ], "to": [ { "role": "Signer 1", "order": 1, "phone": "+1XXXXXXXXXX", "method": "sms", "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "language": "fr", "reassign": "1", "reminder": 5, "sms_message": "Hi, here is a document for signature from {sender_email}", "phone_invite": "+1XXXXXXXXXX", "redirect_uri": "https://unique-solutions.com", "expiration_days": 27, "redirect_target": "blank", "close_redirect_uri": "https://unique-solutions.com", "authentication_type": "phone", "decline_by_signature": "1", "decline_redirect_uri": "https://unique-solutions.com", "authentication_sms_message": "Enter the password to unlock the document:{password}" }, { "role": "Signer 2", "order": 2, "phone": "+1XXXXXXXXXX", "method": "phone_call", "role_id": "49XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "reassign": "1", "phone_invite": "+1XXXXXXXXXX", "expiration_days": 27, "authentication_type": "phone", "decline_by_signature": "1" }, { "role": "Signer 3", "order": 3, "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "password": "1234", "reassign": "1", "reminder": 5, "phone_invite": "+1XXXXXXXXXX", "expiration_days": 27, "authentication_type": "password", "decline_by_signature": "1" } ], "from": "sender@email.com", "cc_step": [ { "name": "CC 1", "step": 1, "email": "cc_recipient1@email.com" }, { "name": "CC 2", "step": 2, "email": "cc_recipient2@email.com" } ], "viewers": [ { "role": "Viewer 1", "email": "viewer@email.com", "order": 1, "message": "You've got a new document to review.", "subject": "New document", "redirect_target": "blank", "close_redirect_uri": "https://unique-solutions.com" } ], "cc_message": "cc Invoice request for Signer 1", "cc_subject": "cc Invoice request" } ``` ## 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 140 characters". * `sms_message` value is blank , code 65536. Message : "SMS message must not be empty". * `phone_invite` value is not valid, code 104833. Message: "The phone_invite value is not valid." * `phone_invite` value is blank, code 104833. Message: "The phone_invite must not be empty string." * Phone number starts with ’+1 and contrains more than 10 digits, code 104833. Message: "The phone_invite value is too long. It should have 12 characters." * Phone number doesn't exist, code 104833. 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: "The phone_invite or email is required. But you cannot use 2 parameters in one time" * Org setting ‘Require Login to Sign’ when the setting is ON, code 65582. Message: "The phone_invite cannot be used with require_login_for_signing setting enabled." * Org setting ‘Electronic Consent Required By Signers’ when the setting is ‘Required by all signers’ OR ‘Required by signers from outside of the organization’, code 65582. Message: “The phone_invite cannot be used with consent setting enabled.” * Org setting 'Invites Must Use Two Factor Authentication' is enabled, code 65622. Message: "The phone_invite must use two factor authentication." **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 '{"cc": ["cc_recipient1@email.com", "cc_recipient2@email.com"], "to": [{"role": "Signer 1", "order": 1, "phone": "+1XXXXXXXXXX", "method": "sms", "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "language": "fr", "reassign": "1", "reminder": 5, "sms_message": "Hi, here is a document for signature from {sender_email}", "phone_invite": "+1XXXXXXXXXX", "redirect_uri": "https://unique-solutions.com", "expiration_days": 27, "redirect_target": "blank", "close_redirect_uri": "https://unique-solutions.com", "authentication_type": "phone", "decline_by_signature": "1", "decline_redirect_uri": "https://unique-solutions.com", "authentication_sms_message": "Enter the password to unlock the document:{password}"}, {"role": "Signer 2", "order": 2, "phone": "+1XXXXXXXXXX", "method": "phone_call", "role_id": "49XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "reassign": "1", "phone_invite": "+1XXXXXXXXXX", "expiration_days": 27, "authentication_type": "phone", "decline_by_signature": "1"}, {"role": "Signer 3", "order": 3, "role_id": "48XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "password": "1234", "reassign": "1", "reminder": 5, "phone_invite": "+1XXXXXXXXXX", "expiration_days": 27, "authentication_type": "password", "decline_by_signature": "1"}], "from": "sender@email.com", "cc_step": [{"name": "CC 1", "step": 1, "email": "cc_recipient1@email.com"}, {"name": "CC 2", "step": 2, "email": "cc_recipient2@email.com"}], "viewers": [{"role": "Viewer 1", "email": "viewer@email.com", "order": 1, "message": "You'\''ve got a new document to review.", "subject": "New document", "redirect_target": "blank", "close_redirect_uri": "https://unique-solutions.com"}], "cc_message": "cc Invoice request for Signer 1", "cc_subject": "cc Invoice request"}' ``` --- *Full reference: https://docs.signnow.com/docs/document-field-invite/operations/post-document-document_id_for_sms-invite---send-invite-via-SMS*