SMS Delivery with the eSignature REST API
Note: For the latest on SMS Delivery, see SMS Delivery Update.
Surveys have shown that people now prefer to receive urgent messages via SMS rather than email. Now, with the DocuSign SMS Delivery feature, you can enhance email notifications with real-time SMS notifications sent directly to a signer’s mobile device. Check out the video!
In this first release of the SMS Notification feature, the SMS notification messages are in addition to email notifications. A later release (no schedule yet) will remove the email requirement.
The SMS Delivery User’s Guide is available on DocuSign Support; you can also find our API 101 guide and how-to on the Developer Center. Meanwhile, here’s a brief introduction to using SMS Delivery via the eSignature REST API v2.1.
Provision your account
Log in to your account using the DocuSign web app. Start the send envelope flow.
If the new Delivery dropdown menu is in the recipient section, then your account has been provisioned with the SMS Delivery feature. Next, use the web app to send an envelope to yourself using SMS Delivery to understand its user experience.
If SMS Delivery is not provisioned for your account, contact DocuSign Support for developer accounts or DocuSign Sales for production accounts.
Plan your envelopes
With SMS Delivery, the odds are high that the envelope will be signed using a mobile device. Test your envelope formats and templates with mobile devices and update the envelope options to provide the best signing experience for your signers. For example, turn on Responsive Signing and investigate Smart Sections.
Choose your authentication method
SMS and phone call identity verification methods are not available with SMS Delivery because they are not effective authentication challenges when SMS is used to deliver access to the signing session. You will need to update your envelopes to use a different authentication technique.
Learn the SMS Delivery capabilities
Read the SMS Delivery guide to understand the capabilities and limitations of the SMS Delivery feature’s first release. For example, with release 1, SMS Delivery can only be used with some types of recipients; there’s a limit of five SMS Delivery recipients per envelope; and more.
Bulk sending with SMS Delivery
The DocuSign web app and the bulk send API methods do not yet support bulk sending with SMS Delivery. But you can use the eSignature REST API to send multiple envelopes that include SMS recipients. Remember to use the API resource limits headers to avoid exceeding your integration key’s hourly limits.
SMS Delivery via the API
If the sender can use SMS Delivery via the DocuSign web app, then an access token for that account member (user) can use SMS Delivery via the eSignature REST API v2.1.
The signer, carbonCopy, and certifiedDelivery objects already have an optional additionalNotifications attribute. It is an array of recipientAdditionalNotification objects. The recipientAdditionalNotification object type now has a new attribute, secondaryDeliveryMethod:
recipientAdditionalNotification object attributes:
- phoneNumber: recipientPhoneNumber object—the SMS Delivery phone number
- secondaryDeliveryMethod: string—the only supported value is "SMS"
JSON example request
{
"signers": [
{
"routingOrder": 1,
"name": "Larry Kluger",
"email": "larry@example.com",
"additionalNotifications": [
{
"secondaryDeliveryMethod": "SMS",
"phoneNumber": {
"countryCode": "1",
"number": "7165551212"
}
}
]
}
]
}
API Notes
- Only eSignature REST API v2.1 is supported.
- The countryCode attribute is the numeric country code for the SMS number. (The Developer Center API reference documentation will be updated.)
- Use country code “1” for the US, Canada, and the other countries in the North American Numbering Plan (NANP).
- Do not include a plus symbol (+) before the numeric country code.
- The number attribute can include a leading zero for countries outside of the NANP. Do not include a leading one or zero for the US or other countries in the NANP.
- Use only the characters 0-9 in the number attribute. Since users may include spaces, dashes or other characters when they input the number, remove any additional characters before sending the number in an API call.
- The additionalNotifications attribute is set to an array. The array must have exactly one element.
- As discussed in the SMS Delivery guide, an email address is also required for the first release of the SMS Delivery feature.
Known issue: Using templates with SMS Delivery
There is a known issue when using SMS Delivery with an envelope created from a template: the templateRole object does not yet support the additionalNotifications attribute. This is issue TT-3902.
The workaround is to create a draft envelope with the templateId and templateRoles attributes and then use the EnvelopeRecipients:update method to update the recipient object(s) with recipientAdditionalNotification objects for SMS Delivery. Include the roleName attribute in the update, and then update the envelope to start processing by changing the status attribute to sent.
Known issue: Composite templates with SMS Delivery
There is a known issue when using SMS Delivery with the Composite templates feature: a recipient attribute does not work as expected if the object includes a recipientAdditionalNotification discussed above. This is issue TT-3872.
The workaround is to create a draft envelope with the composite template and recipient objects (but without the SMS Delivery objects), and then use the EnvelopeRecipients:update method to update the recipient object(s) with recipientAdditionalNotification objects for SMS Delivery. Include the roleName attribute in the update, and then update the envelope to start processing by changing the status attribute to sent.
SDK Support
The current eSignature REST API v2.1 SDKs for C#, Node.js, Java, PHP, Python, and Ruby include support for the recipientAdditionalNotification and recipientPhoneNumber objects as discussed above.
Summary
SMS Delivery is a powerful new feature for your DocuSign API applications. We look forward to hearing about your use cases!
