Skip to navigation
How-to guidesSend a signature request (remote signing)

How to request a signature by SMS or WhatsApp delivery

View as Markdown
eSignature REST API 2.1 only

This topic demonstrates how to send a signature request via an SMS or WhatsApp message. Recipients receive a notification from SMS or WhatsApp with a signing link that they can use to open and electronically sign a document using the Docusign mobile app or the Docusign website.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/restapi
Where <domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.
{CC_COUNTRY_CODE}The country code corresponding to the CC_PHONE_NUMBER.
{CC_PHONE_NUMBER}The phone number of the carbon copy recipient to whom the SMS or WhatsApp notification will be sent.
{CC_RECIPIENT_NAME}A string value for the name of the carbon copy recipient.
{COUNTRY_CODE}The country code corresponding to the PHONE_NUMBER.
{DELIVERY_METHOD}The delivery method specified for a given recipient. One of:

Email, fax, SMS, WhatsApp, or offline

The SMS and WhatsApp delivery methods are limited to signer, carbonCopy, and certifiedDelivery recipients.
Documents to be signedYou must provide at least one document to be signed. Documents used in this how-to:
  • DOCX file
  • PDF file
  • A third document in HTML is constructed dynamically by the sample code
{PHONE_NUMBER}The phone number of the signer to whom the SMS or WhatsApp notification will be sent.
{SIGNER_NAME}A string value for the full name of the signer.

Step 1. Obtain your OAuth token

To make the API call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

See Confidential Authorization Code Grant for guidance on your options to get an Confidential Authorization Code Grant OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. Create the envelope definition

To request a signature, you need to create a new envelope definition. The accompanying code shows how to create an individual envelope by defining a method named makeEnvelope that creates the envelope definition. The makeEnvelope method:

  • Creates and attaches multiple documents to the envelope.
  • Sets signer and CC recipient data.
  • Creates a routing order for the documents.
  • Creates and assigns signable fields to specific signers within the documents.To send an SMS or WhatsApp notification, you need to edit the signer’s phnoneNumber field to include values for number and countryCode. You also have to set the deliveryMethod field to either “SMS" or "WhatsApp". You should make these changes for each recipient you want to notify via SMS or WhatsApp. The accompanying code also demonstrates how to notify a carbon copy recipient via SMS or WhatsApp by editing the same fields in the carbonCopy object.
printf \
'{
    "emailSubject": "Please sign this document set",
    "documents": [
        {
            "documentBase64": "' > $request_data
            cat $doc1_base64 >> $request_data
            printf '",
            "name": "Order acknowledgement",
            "fileExtension": "html",
            "documentId": "1"
        },
        {
            "documentBase64": "' >> $request_data
            cat $doc2_base64 >> $request_data
            printf '",
            "name": "Battle Plan",
            "fileExtension": "docx",
            "documentId": "2"
        },
        {
            "documentBase64": "' >> $request_data
            cat $doc3_base64 >> $request_data
            printf '",
            "name": "Lorem Ipsum",
            "fileExtension": "pdf",
            "documentId": "3"
        }
    ],
    "recipients":
    {
        "carbonCopies":
        [
            {
            "phoneNumber":
                {
                    "countryCode": "'"${CC_PHONE_COUNTRY}"'",
                    "number":"'"${CC_PHONE_NUMBER}"'"
                },
            "name": "'"${CC_NAME}"'",
            "recipientId": "2",
            "routingOrder": "2",
            "deliveryMethod": "'"${DELIVERY_METHOD}"'",
            }
        ],
        "signers":
        [
            {
            "phoneNumber":
                {
                    "countryCode": "'"${SIGNER_PHONE_COUNTRY}"'",
                    "number":"'"${SIGNER_PHONE_NUMBER}"'"
                },
                "name": "'"${SIGNER_NAME}"'",
                "recipientId": "1",
                "routingOrder": "1",
                "deliveryMethod": "'"${DELIVERY_METHOD}"'",
                "tabs":
                {
                    "signHereTabs":
                    [
                        {
                            "anchorString": "**signature_1**",
                            "anchorUnits": "pixels",
                            "anchorXOffset": "20",
                            "anchorYOffset": "10"
                        },
                        {
                            "anchorString": "/sn1/",
                            "anchorUnits": "pixels",
                            "anchorXOffset": "20",
                            "anchorYOffset": "10"
                        }
                    ]
                }
            }
        ]
    },
    "status": "sent"
}' >> $request_data

Step 3. Create and send the envelope

With the envelope definition and the attributes defined for the signer, document, and custom fields, you can now use the Envelopes:create API method to create an envelope and send it, adding your access token and base path to the request header.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --data-binary @${request_data} \
     --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes \
     --output $response

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

In addition, the signer receives an SMS or WhatsApp message containing a signing link that they can use to open and electronically sign a document using the Docusign mobile app or the Docusign website. After signing is complete, the recipient receives a carbon copy (CC) of the email that includes all of the completed and signed documents.

Sample response
{
  "envelopeId": "e319acf5-xxxx-xxxx-xxxx-8bd6eae9abb7",
  "uri": "/envelopes/e319acf5-xxxx-xxxx-xxxx-8bd6eae9abb7",
  "statusDateTime": "2023-04-06T19:38:30.6530000Z",
  "status": "sent"
}

Next steps