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

How to request a signature by multiple delivery methods

View as Markdown
eSignature REST API 2.1 only

This topic demonstrates how to request a signature using email as the primary delivery method, with either SMS or WhatsApp as an additional delivery method.

In this configuration:

  • You must set email as the primary delivery method.
  • You can configure only one secondary delivery method per recipient: SMS or WhatsApp. You cannot configure both SMS and WhatsApp for the same recipient.
  • Secondary delivery methods are supported only for signer (Needs to Sign), carbonCopy (Receives a Copy), and certifiedDelivery (Needs to View) recipient types.

Recipients receive an email notification for the signing request, along with an SMS or WhatsApp notification. The signing link in any of these notifications can be used to open and electronically sign the 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_EMAIL}A string value for the email address of the carbon copy recipient.
{CC_RECIPIENT_NAME}A string value for the name of the carbon copy recipient.
{COUNTRY_CODE}The country code corresponding to the PHONE_NUMBER.
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.
{SECONDARY_DELIVERY_METHOD}The secondary delivery method specified for a given recipient. One of: SMS or WhatsApp. Secondary delivery methods are limited to signer, carbonCopy, and certifiedDelivery recipients.
{SIGNER_EMAIL}A string value for the email address where the signer will receive a notification of the signing request.
{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 carbon copy recipient data.
  • Creates a routing order for the recipients.
  • Creates and assigns signable fields to specific signers within the documents.

To use multiple delivery methods, configure the signer object by setting deliveryMethod to Email, and add an entry to the signer’s additionalNotifications array. In this entry, set secondaryDeliveryMethod to SMS or WhatsApp, and provide the recipient’s phone number by setting values for number and countryCode in the phoneNumber object. You should make these changes for each supported recipient you want to notify via email and SMS or WhatsApp. The accompanying code also demonstrates how to configure a carbon copy recipient using 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":
        [
            {
                "name": "'"${CC_NAME}"'",
                "email": "'"${CC_EMAIL}"'",
                "recipientId": "2",
                "routingOrder": "2",
                "deliveryMethod": "Email",
                "additionalNotifications": [
                    {
                        "phoneNumber":
                        {
                            "countryCode": "'"${CC_PHONE_COUNTRY}"'",
                            "number":"'"${CC_PHONE_NUMBER}"'"
                        },
                        "secondaryDeliveryMethod": "'"${DELIVERY_METHOD}"'"
                    }
                ],
            }
        ],
        "signers":
        [
            {
                "name": "'"${SIGNER_NAME}"'",
                "email": "'"${SIGNER_EMAIL}"'",
                "recipientId": "1",
                "routingOrder": "1",
                "deliveryMethod": "Email",
                "additionalNotifications": [
                    {
                        "phoneNumber":
                        {
                            "countryCode": "'"${SIGNER_PHONE_COUNTRY}"'",
                            "number":"'"${SIGNER_PHONE_NUMBER}"'"
                        },
                        "secondaryDeliveryMethod": "'"${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 recipients, 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 email and an SMS or WhatsApp message. They can use the signing link in any of these notifications to open and electronically sign a document using the Docusign mobile app or the Docusign website. After signing is complete, the recipients receive a carbon copy 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