From the Trenches: Configuring and troubleshooting your DocuSign third-party integration
In today’s blog post, I’ll walk you through some of the main points to consider when connecting to DocuSign using a third-party integration, in particular when you are required to use your own Integration key.
Also, I will cover some of the most common issues and errors during the initial steps of the integration process.
What is third-party integration?
Integrations provide access to DocuSign's signature functionality for certain industries or business functions, such as HR, sales, finance, and procurement. DocuSign for Workday, DocuSign for SAP, and DocuSign for Salesforce are a few examples.
Some DocuSign integrations are created by DocuSign; others, however, are created by external developers, either to integrate with their own products or to integrate with their client’s IT infrastructure; such an application is called a third-party integration. Third-party integrations are developed by integration service providers also referred to as ISVs (Independent Software Vendors), who are in charge of controlling how integrations function, where they are hosted, and how they are configured. All types of integration use the same DocuSign APIs, regardless of how diverse their user interfaces and functionalities are, and the integration developer has discretion over how this is done.
My ISV app requires me to get an integration key
To access DocuSign APIs, DocuSign requires that an integration be registered and assigned an integration key: this is a 32-digit number that uniquely identifies the integration, and it’s used to authenticate the integration’s API requests with DocuSign API servers. DocuSign recommends integration developers to create a single integration key for their integration and use it with all their customers; however, for various reasons, some ISVs may choose to require their customers to create and manage their own integration key.
How do I do that?
Integration keys are managed in DocuSign accounts. Getting your own integration key requires you to act as a developer who would create and manage your integration key:
- Integration keys can be generated only in DocuSign Developer accounts. Because of this, the first step is to create a developer account if you don’t have one already.
- In your developer account, generate a new integration key.
- Configure your integration key by generating a secret key, RSA key pair, and redirect URI. Your integration developer should be able to provide you with the redirect URI to use for your integration.
- Configure your third-party integration with your config details from step 3 and test the integration to make sure you are able to create and send envelopes. Note: Depending on the authentication process, integration providers may have different requirements; contact your integration providers and follow their guidance.
- At this point, your integration works, but to send valid DocuSign envelopes, you must migrate your configuration to a DocuSign production account. To do this, you must initiate a GoLive review.
- If your integration passes review, you will need a production account, if you don’t already have one, into which to migrate your integration key. The go-live process replicates your integration key into your production account; then you will need to repeat steps 3 and 4 in your production account to configure your production integration key. Note: You can continue to simultaneously use the same integration key in both the developer and production environments, assuming your integration provider allows for both demo and production configurations at the same time.
Common issues and errors
Authentication errors
Calls to DocuSign APIs require authentication, in which a DocuSign user grants the integration consent to access the API and perform certain functions (known as scopes) on their behalf. DocuSign supports three OAuth authentication types: Authorization Code Grant, JSON Web Token (JWT), and Implicit.
The most common error for integrations using JWT as an authentication method is “consent_required”. If you see this error, this means that the consent-granting process was not automated by the integration, and you as a user will need to provide it manually by building the consent URI. See Step 1 of How to obtain individual consent for instructions. Also, you can read more in the blog post OAuth JWT: Granting Consent.
Go-Live issues
Note: Go-Live is needed only if your ISV requires you to use your own integration key. If your ISV does not require you to create an integration key, you can connect directly to your chosen production account and don’t have to perform the Go-Live process.
Go-Live is an automated process that is designed to test the integration for compliance with DocuSign API usage policies, and customers will need to complete the process in order to use their integration key in production. The Go-Live process retrieves the customer's most recent 20 calls from their integration and examines them for polling (making repeated calls to the same envelope resource) and errors.
Sometimes the integration polls, which causes the review to fail. A simple example would be if the integration checked the status of the envelopes every minute.
Since DocuSign Support has no control over the integration or the Go-Live review, we recommend you contact your ISV provider to resolve the polling problems.
Permission errors
Many common errors are to do with user permissions or account plans. These occur when an integration attempts to perform an action for which the user who granted consent doesn’t have permission, or for which the user’s account plan doesn’t include the required DocuSign feature.
You can tell whether an issue is linked to DocuSign or the integration provider because all DocuSign API errors have the same structure. The DocuSign API error format is
{
"errorCode": "SOME_ERROR_CODE",
"Message": "Clarification message"
}
There are, however, always cases in which the integration provider has chosen to replace the API error with their own syntax or formatting.
User permission errors
Errors frequently occur when a user attempts to execute an action for which they do not have permission.
For example:
{
"errorCode": "USER_LACKS_PERMISSIONS",
"Message": "This User lacks sufficient permissions. The requesting user must be either a sender or editor of the envelope."
}
Because of privacy protection rules, through the API, envelopes can be accessed only by specific users.
- The owner/sender of the envelope
- Envelope signers
- Users with the DSAdmin permissions profile from the same account
- Users the envelope is shared with through envelope sharing
Any other user trying to access the envelopes will trigger the error message above.
Another widespread user permission error is:
{
"errorCode": "USER_LACKS_PERMISSIONS",
"Message": "This User lacks sufficient permissions. User does not have the permission to send envelopes"
}
DocuSign has three default permission profiles:
- DS Admin
- DS Sender
- DS Viewer
The above error will be triggered by a DS Viewer trying to send envelopes. User permission errors can be resolved by any account administrator by updating the user’s permission profile.
Account permission errors
Depending on whether the feature is already included in your plan, DocuSign Support may enable it. Otherwise, the feature will need to be purchased if it is not included in your account plan subscription.
Examples of account permission errors are:
{
"errorCode": "ACCOUNT_LACKS_PERMISSIONS",
"Message": "This Account lacks sufficient permissions. Account lacks permission to send Envelopes over SMS."
}
{
"errorCode": "ACCOUNT_LACKS_PERMISSIONS",
"Message": "This Account lacks sufficient permissions. Connect not enabled for account.."
}
{
"errorCode": "ACCOUNT_LACKS_PERMISSIONS",
"Message": "This Account lacks sufficient permissions. Document Visibility has been specified. This account does not have document visibility turned on."
}
User Info error
Another common error that does not really fit in the above categories is the “UserNotFound” error. A relatively small number of DocuSign users have memberships that are in an atypical state, which otherwise does not impact functionality.
For more information, see our support guide UserInfo call returns UserNotFound for a Specific Valid User.
Who should I reach out to for support?
The integration provider or your account admin should always be your first point of contact unless the error relates to a DocuSign account plan feature. Your integration provider or account admin will be familiar with how the integration was created and have access to configurations, logs, and code.
Nevertheless, if your issue was not resolved by the third-party integration support team and you need to contact DocuSign support, go to our Support site and select APIs & Development (For Developers|Technical Resources) > Third-Party integrations (third-party integrations only).
Also, you can speed up the case resolution process, by including the third-party engineer contact and your API logs (see how to collect API logs).
