DocuSign Developer FAQs - eSignature API

The following are answers to some of the most common questions we receive about our eSignature API and the topic of Legacy Authentication deprecation. For Developer FAQs on other topics, see the DocuSign Developer FAQs - Table of Contents, or the links under References at the end of this page.

eSignature API

Legacy Authentication Deprecation

eSignature API

The eSignature REST API and SOAP API allows you to integrate DocuSign eSignature into your app, workflows and more.

Why am I not seeing my activity in API logs?

When following our guide to capture eSignature REST API request logs, it is important to remember that logging is user based, not account based. If you review the files in your downloaded zip file and do not see the traffic you expect from your API you may have logged in to the DocuSign eSignature web application as the wrong user. Another possibility is that you did not clear logs before enabling them or that you took several actions in the web console.

Why am I receiving the error { "errorCode": "PARTNER_AUTHENTICATION_FAILED"} and how do I fix this?

The PARTNER_AUTHENTICATION_FAILED Error code with the message "The specified Integrator Key was not found or is disabled." is returned when you attempt to use our deprecated legacy header authentication and supply and incorrect integration key (also called a clientId). This may be due to a completely invalid GUID or submitting a request to a production environment with a key that is valid in demo, but has not been promoted to a live key in production.

Why am I seeing the error {"errorCode":"ACCOUNT_NOT_AUTHORIZED_FOR_ENVELOPE"} when updating recipients?

This error is a result of trying to do an embedded signing session on an envelope that was sent as a remote (email) recipient. To make a recipient embedded you assign a clientUserId property. If you want to use a “hybrid” pattern and give signers the option of initiating the signing session from the email that DocuSign sends them, or within your application portal, then you can define your recipient with a clientUserId property and set the embeddedSigningStartUrl property to “SIGN_AT_DOCUSIGN.”

Why am I seeing the error {"errorCode":"USER_LACKS_PERMISSIONS"} when voiding the envelope?

In order to void an envelope, you need to be an envelope participant, an administrator on the account the envelope was sent from, or you need to have the sender’s sent folder shared with the user you’re authenticated as while making the call.

Why is a recipient's language changing when I'm defining an EmailSubject or EmailBody for them?

When using the EmailNotification parameter to set a custom EmailSubject and EmailBody for each individual recipient, it's also recommended to use the SupportedLanguage parameter to explicitly define the expected language for them. While generally the SupportedLanguage parameter can be left empty with little impact, in some cases, correcting an envelope with the SupportedLanguage left empty can result in the language changing unexpectedly.

Why am I getting the error "errorCode": "REQUEST_ENTITY_TOO_LARGE"?

This indicates that you're trying to pass too much data in one api call. The limit for one call is 25mb, if you are trying to pass more than that you will get this error.
You can always upload envelope documents using separate calls to prevent this. Please see our eSignature API rules and resource limits for more information.

Why is the signature missing in the document downloaded via API?

One scenario where the signature does not appear on the downloaded document is when the signer used the Print & Sign option to upload or fax a wet-signed copy of the document. The document the signer uploaded or faxed would be separate from the original document sent to the signer, and is available if the envelope documents are downloaded as combined (i.e., single PDF) or archive (as a .zip folder).

How do I configure recipients as embedded signers when creating envelopes through API?

To configure a recipient as an embedded signature you must include the "clientUserId" inside the request. Once a recipient is designated as an embedded signer they will not receive e-mails to sign a document unless “"embeddedRecipientStartURL": "SIGN_AT_DOCUSIGN"” is also included inside the request. More information can be found here.

How do I make a recipient as a signing group via API?

To create an envelope recipient as a signing group rather than an individual recipient, instead of adding an email address for your recipient, the “SigningGroupId” property has to be set, with the desired signing group ID. Example: “SigningGroupId”: “12345”. If you do not have your signing group IDs available offhand, you can refer to this documentation on how to request them via API.

Legacy Authentication Deprecation

DocuSign has announced the deprecation of Legacy Authentication for REST API. OAuth 2.0 will be required for authentication in new apps starting August 16th 2021. Full deprecation of non-OAuth 2.0 authentication flows will follow in September 2022.

What is the current plan to deprecate Legacy Authentication?

DocuSign's deprecation plan for Legacy Authentication was announced in July 2021. A new banner will be added to the Demo site shortly after, followed by a similar alert message in the Production environment. Beginning August 16th of 2021, all new REST Integration Keys will be required to use OAuth 2 for authentication. In September of 2022, all existing applications must begin using OAuth 2 for authentication.

Will this affect current implementations or only net new integrations?

This will affect newly created REST Integration Keys starting on August 16th. Current Integration Keys will still be viable until the next phase of the deprecation plan.

What about SOAP?

Support for App Passwords for our SOAP APIs are presently under development. (SOAP will not require OAuth 2) The official deprecation plan is scheduled to be released in August of 2021.

Where can I find the full deprecation plan?

This developer blog post provides an outline of important dates, implications of the deprecation to existing and new integrations, and other resources you may find helpful.
The schedule and related announcements will be published via the Product release notes through September 2022.

Will we still be able to use SOBO?

The recommendation for using SOBO with OAuth 2 is to utilize JWT. JWT allows you to impersonate a specific user once they’ve given your integration permission to generate tokens on their behalf. A list of userIds can be obtained by making an API call to the v2.1/accounts/{accountId}/users endpoint. Consent will still need to be granted, which can be done in one of three ways which are outlined on our following blog page:

Will I need to change how I go about looking up my users to verify their accountId and baseUrls?

Yes, legacy authentication is meant to run against the login_information endpoint, which is part of the legacy system. Looking up a user when using an OAuth token should instead be pointed to the userInfo endpoint:

Do you have any guidance on how to migrate away from Legacy Authentication?

We have a guide avialable on our Developer Center located at