--- title: "SMS invite" url: "https://docs.signnow.com/docs/sms-invite" type: "page" section: "Documentation" slug: "sms-invite" --- # SMS invite # About SMS invite Apart from using email, you can also invite people to sign documents by SMS. A recipient gets a message with a link to a document or document group. SMS invites are available for US and Canadian numbers only. SMS signature request is available for a [document field invite](/docs/document-field-invite/operations/post-field_invite) and [document group field invite](/docs/doc-group-field-invite/operations/invite-to-sign-document-group). Different signers of one invite can receive their invites by email or SMS. > A user in an organization (workspace) with required electronic consent cannot send SMS invites. You can turn this setting off in your [account](https://app.signnow.com/) or by using the [Update organization settings](/docs/organization/operations/put-v2-organizations-org_id-settings) request. ## Send a document field invite by SMS ### Step 1: Authentication [Authenticate](/docs/authentication) your application for further requests. ### Step 2: Upload document [Upload](/docs/entities) a document to be signed. ### Step 3: Add fields [Add](/docs/fields) fields to the document. ### Step 4. Get role ID Make a [Get document](/docs/document/operations/get-document) request to retrieve the role or role ID. ```bash curl --request GET \ --url https://api.signnow.com/document/{{document_id}} \ --header "Authorization: Bearer {{access_token}}" ``` - The `roles` array lists the role names and IDs of recipients who can sign the document. You need either a role or role ID, but you can use both. If you use both, ensure the roles and IDs correspond. ```json { "roles": [ { "unique_id": "6e9580fa76ba4edca18fa6e680a36d10a6bab503", "signing_order": "1", "name": "Signer 1" } ] } ``` > **Note**: In the invite, all the roles from the document must be assigned to signers. > The `approver_roles` and `viewer_roles` are populated only after the field invite is created. ### Step 5: Send document invite by SMS Send a [document field invite](/docs/document-field-invite/operations/post-field_invite) by SMS. Required SMS invite fields: - `to`: array of recipients - `phone_invite`: phone number to send an SMS to. - `role` (or `role_id`): recipients's role or role ID. Can be found in the [Get document](/docs/document/operations/get-document) response. - `order`: recipient's order. - `from`: sender's email address. Must be the email address associated with your SignNow account. Find optional parameters in the [request body](/docs/document-field-invite/operations/post-field_invite#request-body) of the document field invite. `subject` and `message` are not supported, but you can add a custom SMS message (max 140 characters) to the `sms_message` field. Use a {sender_email} placeholder in the message. The link to the document and an opt-out notice are automatically added at the end of the SMS. If a custom message is not added, a recipient gets a default message: “ has sent you a document. Follow the link to view the document . ```bash curl --request POST \ --url https://api.signnow.com/document/{{document_id}}/invite \ --header "Authorization: Bearer {{access_token}}" \ --header "Content-Type: application/json" \ --data '{ "to": [ { "phone_invite": "+12124567890", "role": "Signer 1", "role_id": "6e9580fa76ba4edca18fa6e680a36d10a6bab503", "order": 1, "sms_message": "Hi, here is an invoice for signature from {sender_email}" } ], "from": "sender@email.com" }' ``` ### Combine email and SMS recipients Different signers of one invite can receive it by email or SMS. Identify each recipient by `email` or `phone_invite` — only one of these parameters at a time. In this example, Signer 1 receives the invite by email, and Signer 2 receives it by SMS with SMS authentication: ```bash curl --request POST \ --url https://api.signnow.com/document/{{document_id}}/invite \ --header "Authorization: Bearer {{access_token}}" \ --header "Content-Type: application/json" \ --data '{ "to": [ { "email": "signer1@email.com", "role": "Signer 1", "role_id": "6e9580fa76ba4edca18fa6e680a36d10a6bab503", "order": 1, "subject": "You have got a new signature request", "message": "Hi, this is an invite to sign a document." }, { "phone_invite": "+12124567890", "role": "Signer 2", "role_id": "7f0691fb87cb5fedb29fb7f791b47e21b7cbc604", "order": 2, "sms_message": "Hi, here is a document for signature from {sender_email}", "authentication_type": "phone", "method": "sms", "phone": "+12124567890", "authentication_sms_message": "Enter the password to unlock the document: {password}" } ], "from": "sender@email.com" }' ``` ## Try out in Postman [Access](https://www.postman.com/signnow-api/signnow-public-collection/collection/65kpga4/signnow-extended-signing-session-features) this flow in Postman and use SMS invites to ensure all your signers receive signature requests. ## Send a document group field invite by SMS ### Step 1: Authentication [Authenticate](/docs/authentication) your application for further requests. ### Step 2: Upload documents [Upload](/docs/entities#step-1-upload-document) documents to your SignNow account. ### Step 3: Add fields [Add](/docs/fields) fields to the documents. ### Step 4. Create a document group Use the document IDs from **Step 2** response to [create a document group](/docs/entities#step-6-create-document-group). ### Step 5. Get roles You can retrieve document roles in two ways: - Make a [Get document](/docs/document/operations/get-document) request for each document in a document group to retrieve the role and role ID. - Make a [Get document group](/docs/document-group/operations/get-document-group-info-v2) request to retrieve role names in the document group. > Recipients with `approve` and `view` actions appear only after the field invite is created. ### Step 6. Send document group invite by SMS Send a [document group field invite](/docs/doc-group-field-invite/operations/invite-to-sign-document-group) via SMS. As an example, send an SMS invite to three recipients in sequence: **Recipient 1** and **Recipient 2** need to sign the documents in the group, while **Recipient 3** needs to approve two documents in the group. Required SMS invite fields: - `invite_steps`: array of steps for the document group invite. - `order`: sequence number of the step. - `invite_actions`: array of recipient phone numbers, roles, and document actions. - `phone_invite`: phone number to send an SMS to. - `role_name` (or `role_id`): recipient's role name. Can be found in the [Get document group](/docs/document-group/operations/get-document-group-info-v2) response. - `action`: recipient's action on a specific document. - `document_id`: ID of the document. Use the `invite_sms` array to customize the SMS invite for each recipient within a step: - `sms_message`: custom text of the SMS invite, max 140 characters. Use the {sender_email} placeholder to automatically add the sender's email address. The link to the document group and an opt-out notice are automatically added at the end of the SMS. If a custom message is not added, a recipient gets a default message: “ has sent you a document. Follow the link to view the document . - `expiration_days`: number of days before the invite expires. - `reminder`: settings for automatic reminders. Different recipients of one invite can receive it by email or SMS: use `invite_emails` and `email` in one step, and `invite_sms` and `phone_invite` in another. Find optional parameters (such as recipient authentication, redirects, decline, and reassign options) in the [request body of the document group field invite](/docs/doc-group-field-invite/operations/invite-to-sign-document-group#request-body). ```bash curl --request POST \ --url https://api.signnow.com/documentgroup/{{document_group_id}}/groupinvite \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "invite_steps": [ { "order": 1, "invite_sms": [ { "phone_invite": "+14075985199", "sms_message": "Hi, here is a document for signature from {sender_email}", "expiration_days": 30, "reminder": { "remind_after": 1, "remind_before": 2, "remind_repeat": 3 } } ], "invite_actions": [ { "phone_invite": "+14075985199", "role_name": "Recipient 1", "action": "sign", "document_id": "bbbb274c788444d39f75e7d01713f1eaf62ff2c0" } ] }, { "order": 2, "invite_sms": [ { "phone_invite": "+14075985197", "expiration_days": 30, "reminder": { "remind_after": 1, "remind_before": 2, "remind_repeat": 3 } } ], "invite_actions": [ { "role_name": "Recipient 2", "phone_invite": "+14075985197", "action": "sign", "document_id": "bbbb274c788444d39f75e7d01713f1eaf62ff2c0" } ] }, { "order": 3, "invite_sms": [ { "phone_invite": "+12075985197", "expiration_days": 30, "reminder": { "remind_after": 1, "remind_before": 2, "remind_repeat": 3 } } ], "invite_actions": [ { "role_name": "Recipient 3", "phone_invite": "+12075985197", "action": "approve", "document_id": "fffff1dab3634c4f84526d9d43244185829a7623" }, { "role_name": "Recipient 3", "phone_invite": "+12075985197", "action": "approve", "document_id": "bbbb274c788444d39f75e7d01713f1eaf62ff2c0" } ] } ] }' ``` ### Combine email and SMS recipients in a document group invite You can combine email and SMS recipients in a single document group invite: use `invite_emails` and `email` for one recipient, and `invite_sms` and `phone_invite` for another. In this example, Recipient 1 receives the invite by SMS with SMS authentication, and Recipient 2 receives it by email: ```bash curl --request POST \ --url https://api.signnow.com/documentgroup/{{document_group_id}}/groupinvite \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "invite_steps": [ { "order": 1, "invite_sms": [ { "phone_invite": "+14075985199", "sms_message": "Hi, here is a document for signature from {sender_email}", "expiration_days": 30 } ], "invite_actions": [ { "phone_invite": "+14075985199", "role_name": "Recipient 1", "action": "sign", "document_id": "bbbb274c788444d39f75e7d01713f1eaf62ff2c0", "authentication": { "type": "phone", "method": "sms", "phone": "+14075985199", "message": "Enter the password to unlock the document: {password}" } } ] }, { "order": 2, "invite_emails": [ { "email": "signer2@email.com", "subject": "You have got a new document group invite", "message": "Hi, this is an invite to sign a document group.", "expiration_days": 30 } ], "invite_actions": [ { "email": "signer2@email.com", "role_name": "Recipient 2", "action": "sign", "document_id": "bbbb274c788444d39f75e7d01713f1eaf62ff2c0" } ] } ] }' ``` --- *Full page: https://docs.signnow.com/docs/sms-invite*