Developer FAQs - DocuSign

DocuSign Developer Frequently Asked Questions (FAQ)

Here are answers to some of the most frequently asked questions we encounter from developers working with the DocuSign APIs.

General Administration

Integration keys

Go Live

Authentication

Templates

Envelope Management


General Administration

Why am I seeing the error “User Lacks Permission” when retrieving form data through eSignature REST API?

This error means that the “Allow the sender to download form data” setting is disabled. To configure this in the eSignature web application navigate to Settings > Sending Settings, and enable the setting Allow sender to download form data.


No. The Legal Disclosure's behavior can only be changed in the eSignature web application, by going to Settings > Legal Disclosure. For more details, see this guide.


Can I transfer Integration Keys between accounts?

Yes, although in most cases there is no need. An integration key is tied to a particular account for management purposes, but that key can be used to make API calls on any account once properly authenticated.

If an integration key does need to be transferred between two accounts, DocuSign Support can do so with authorization from administrators on both the current account and the destination account. If one user is an administrator of both accounts, they can sign for both roles.

To request an integration key transfer, open a case with DocuSign Support and provide the following:

  • Environment (Demo or Production):
  • Integration Key:
  • Source account ID:
  • Email address of source account admin:
  • Destination account ID:
  • Email address of destination account admin:

Support will send an envelope requesting authorization, and once that is signed the key will be transferred. Note that keys are not "transferred" between Demo and Production - if a key needs to be enabled in the Production environment, it will need to go through the Go Live process.


Integration keys

Integration keys identify your application to DocuSign for the purpose of communicating with DocuSign APIs. Discover what integration keys are, who does and does not need an integration key, and how to manage them.


What is an integration key?

An integration key is a GUID that identifies an application that integrates with DocuSign REST and SOAP APIs. Integration keys are used by the DocuSign OAuth flows—Authorization Code GrantImplicit Grant  and JSON Web Token (JWT) Grant —to obtain access tokens. Integration keys are not used to identify specific accounts or users.


Who needs an integration key?

Any organization or individual who is developing an application, plug-in, or process that sends API requests to DocuSign needs an integration key. For example, if the application, plug-in, or process you are creating uses the eSignature REST or eSignature SOAP API, you will need an integration key.


Who does not need an integration key?

Applications that do not need access tokens to call an API do not need integration keys. This includes PowerForms initiated via their URL, clickwraps that use the JavaScript code produced by DocuSign for embedding in web pages, and DocuSign Connect listeners that do not call a DocuSign API.


Who should administer the integration key?

Integration keys should be managed by the organization that owns the application or integration. Most commonly, DocuSign customers integrate DocuSign features into their existing internal or customer-facing applications. As the owner of their existing applications, they would be the owner and administrator of their integration keys.

In other cases, an implementation partner or third-party consultant may create an application or integration on behalf of a DocuSign customer. In these scenarios, the customer is the owner of the application or integration and would be responsible for management of related integration keys.

In cases where a ISV (Independent Software Vendor) partner builds something for resale, the ISV partner owns the application and would be responsible for administration of the key. ISVs should avoid requiring customers to create or manage integration keys to be used with their software.


What are the best practices for ISV applications regarding the creation and management of integration keys?

It is best practice for the creator (or owner) of an integration to create and manage any integration keys required to communicate with the DocuSign system. For our Independent Software Vendors (ISVs), we recommend this practice for two reasons:

  1. The Go Live process was designed for developers, and end users who are required to Go Live in order to use software that they have purchased through an ISV often have no background in software development. DocuSign Support has received significant feedback from users related to the challenges of taking an integration key live.
  2. When an ISV requires their customers to use their own integration key, it is often unclear whom to contact when an issue with an integration is surfaced, on the part of both the customer who is using the application and the DocuSign Support team, who may need to refer the user to the application developer.
  3. ISV Partners, participating in the ISV Referral Program, should email partners@docusign.com or their Partner Representatiive to schedule an App review prior to Go-Live process.
 

ISV SaaS applications that can secure their integration key and related secrets or RSA keys should use only one integration key for the application. This includes multi-tenant and multi-instance architectures.

Even if an instance of the application is dedicated to a single ISV customer, that instance should use the one integration key obtained by the ISV, so long as the integration key and its settings can be hidden from the ISV customer. For instanced applications, DocuSign prefers that the ISV’s customer not have access to the integration key; it should be managed and controlled by the ISV.

If the ISV creates an instance of the application for a customer, and the customer has complete control over the instance and its settings, then the customer needs to create an integration key.


How do I create an integration key?

Integration keys are created in developer sandbox accounts. Integration keys cannot be directly created on the production systems; please refer to Apps and Keys the DocuSign eSignature Admin Guide for reference.

Once a developer has built his or her application or integration, then the integration key is promoted to production through the Go Live process.

When a key is live in production, it is shown in the Apps and Keys section of eSignature Admin on the production account(s) of the administrator who promoted the key.


Go Live

Go Live is DocuSign's process for migrating an integration created in the demo environment to the production environment. Go Live is necessary before you can perform real transactions in your integration through the DocuSign APIs.


Why does DocuSign have a Go Live process?

The Go Live process is part of DocuSign’s audited trust processes. It helps ensure the stability of the DocuSign platforms and provides a programming check to the developer. The Go Live process is required for all new API integrations.


What is required to complete the Go Live process?

To go live with the eSignature API you need a developer sandbox account and integration key, 20 or more API calls run using the key in a 24-hour period, and an active production DocuSign account with a supported plan. You also need administrator privileges for the live production account to link the key.


Does the Go Live process cost anything?

No, there is no charge for the Go Live process, and you may promote as many integration keys to the production environment as you would like. All you need is a live DocuSign account on an appropriate plan to which to promote the key, as well as administrator privileges to the account.


How long does the Go Live process normally take?

The automated process can take anywhere from a few hours to three business days. If your integration completes 20+ transactions in 24 hours that comply with DocuSign's resource limits, in addition to having an active live DocuSign account and administrator access to the account, the process can take as little as a few hours.


Will my integration key change after Go Live?

No. After the Go Live process is completed, a new integration key is created in the production environment. The new production integration key will have the same value (GUID) as the developer sandbox integration key, but will otherwise be a completely separate key. The integration key will show a status of live on the developer sandbox account after Go Live completes successfully.

Note: Only the integration key is copied to production, not the configuration. Developers need to configure redirect URIs, secret(s), RSA key pairs and any other settings they wish to transfer from their developer sandbox to their production account.

What endpoint should I use to authenticate in the production environment after Go Live?

In the production environment post-Go Live, your application needs to be updated to use production endpoints and related values:

  • The URL for the authentication server needs to be updated to https://account.docusign.com
  • The base URI for API calls must also be changed: Call the UserInfo endpoint to determine the base URI and account information to interact with the DocuSign API service.
  • In addition, if the JSON Web Token (JWT) Grant authorization flow is used, remember to update the impersonated user’s GUID to the value of the API username on a production account.

What are the most common Go Live errors and what steps can I take to troubleshoot?

See the Go Live Troubleshooting Guide to discover how to handle common errors you may encounter during Go Live.


How do I enable and download API logs?

API logging is set on a per-user basis and can be enabled on the Privacy & Security page in your DocuSign account preferences. In the Request Logging section, you can Enable Logging, Disable Logging, Download Logs and Clear Logs.

Enabling logging will capture 50 requests and then disable logging automatically. Logs captured can be downloaded in the form of a ZIP file. If you need to capture more logs, you will need to clear the logs and enable logging again to capture 50 more requests; see API Request Logging for more details.

To see the API logs for your application, login to DocuSign eSignature as the user whose user ID is associated with the application’s access tokens, and then download the logs. If the application impersonates a user, only that user can download the relevant API logs.


What constitutes 20+ successful calls for Go Live?

To pass the go-live process, you'll need to make 20 or more consecutive successful API calls that fall within our guidelines. For additional information, please see our API Rules and Limits documentation.


During Go Live, my production account was not accepted, with the message “The account is not the right type.” What type of account is needed?

The production account used to manage your integration key in production must be a Business Pro account or higher. Ask your DocuSign salesperson if you have questions.


What do the “Under Review”, “Review Expired” and “Review Passed” statuses mean during go-live?

  • Under Review – You will see this status after initiating integration key review process by selecting “Start Go-Live Review” dropdown for your ikey. DocuSign system is checking your API calls for the specified time period
  • Review Passed – You ikey has passed the initial tests and is ready to be promoted to a production account of your choice. At this point you will need to login to your production account by pressing the “Go Live” button from your review results window.
  • Review Expired – ikey passed the review but was never submitted to be linked to a production account. If the ikey is not submitted within a 90-day period, review expires and needs to be done again.

Authentication

All integrations with DocuSign APIs must authenticate in order to make API calls.


What types of API authentication are supported? Are examples available?

DocuSign's eSignature REST API supports and has examples for Authorization Code GrantImplicit Grant and JSON Web Token (JWT) Grant authentication.


How can I find my user ID for authentication?

While you can use the API to query for the user ID for any member of your account, you need one user ID to get started with JWT Authentication. To find your own user ID, navigate to Settings > Apps and Keys. To find the user ID for any other member of the account, navigate to Settings > Users > Edit.


Detailed documentation on application consent is available in the Developer Center. Individual consent is obtained by directing the user to an authorization URI. An organization administrator can grant blanket consent to an application through the Organization module; however, this blanket consent only applies to users with email addresses under domains claimed by the organization.


What is a refresh token, and how is it used?

Refresh tokens are used in the Authorization Code Grant workflow to generate new authorization tokens without requiring end-user interaction. Standard refresh tokens last for 30 days from the initial consent grant. If the extended scope was granted, new refresh tokens can be generated as long as the currently held refresh token is less than 30 days old. Full documentation is available in the Developer Center.


Can I use the same integration key, client secrets, or RSA key pairs between the developer sandbox and production environments?

No. During the Go Live process, an integration key is transferred from developer sandbox to production. While the key's GUID will not change, the developer sandbox and production environments are separate instances, so new client secrets and RSA keypairs must be generated.


What scopes are supported in the eSignature API?

For the eSignature REST API, the scopes are signature, extended, and impersonation:
  • signature — Allows your application to create and send envelopes and obtain links to start signing sessions.
  • extended — Without this scope, a refresh token will last 30 days from the initial consent grant. With this scope, new refresh tokens can be generated indefinitely. This scope may only be used in Authorization Code Grant authentication.
  • impersonation — Allows your application to access a user’s account and act on their behalf even when that user is not present. This scope is only used by JWT Grant authentication. 

Multiple scopes can be requested at once, separated by spaces in the authorization URL.


Can an OAuth access token's lifetime be changed?

No. JSON Web Token (JWT) grant tokens have a fixed lifetime of one hour and the Authorization Code Grant and Implicit Grant access tokens have a fixed lifetime of eight hours. If your application makes an API call with an expired token, it will encounter an authorization failure error and must request a new token to proceed.


Does DocuSign have OAuth code examples?

Yes. You can find OAuth code examples in our Developer Center:


Detailed documentation on application consent specific to the JWT Grant is available in the Developer Center.

JWT consent can be granted administratively by the system administrator if your account includes the Access Management feature (previously known as the “org admin” feature) and you have claimed the email domain of the impersonated users’ email addresses.

JWT consent can also be granted individually; each user who will be impersonated must grant permission themselves.

To grant consent individually, use the same consent process as Authorization Code Grant with a few exceptions:

  • The scopes must include signature and impersonation (and perhaps other scopes too, depending on the API you’ll be using).
  • Don't use the authorization code that is returned to request a token. Just ignore it: the important side effect is that the user has granted consent to your integration key.
  • The consent is stored on DocuSign servers until it is revoked by a user, so typically, you only need to get user consent once.

When using JWT authentication, how do I troubleshoot an invalid_grant or other errors?

The invalid_grant error is a generic error response that means something is incorrect in the JWT assertion. In order to determine what is wrong, refer to the error_description parameter in the response. If the error_description isn't readily available in your application, we recommend setting up error logging that captures the full error response.

Authentication error responses:

  • consent_required: If using individual consent, make sure consent has been granted for the desired scopes. The signature impersonation scope is the minimum required for JWT authentication, but other scopes may be necessary for Rooms or Admin functions.
  • invalid_subject or user_not_found: Something is likely wrong with the sub (subject) value in the assertion. Confirm that the value is a valid GUID user ID (not an email address) of a user that is active in the relevant environment.
  • Issuer_not_found: The integration key in the iss (issuer) parameter is unavailable in the current environment. This can also mean a mismatch in the aud (audience) value and the environment being hit: for example, using an aud value of account.docusign.com while requesting a token from https://account-d.docusign.com/oauth/token.
  • no_valid_keys_or_signatures: This error covers several cases:
    • There is an issue with the private key used to sign the assertion (for example, using a demo key in the production environment).
    • The assertion is missing an exp (expiration) parameter
    • The aud (audience) parameter is invalid - confirm the audience value is exactly account.docusign.com or account-d.docusign.com with no https:// prefix or trailing slash (/).
    • An nbf (not valid before) parameter is defined, and that time has not been reached. The nbf parameter is optional and can be removed from the assertion, but if it is present, it must be a time in the past.
  • expired_grant: The assertion has expired. The exp (Expiration) parameter must be a time in the future.

Admin consent requires a claimed email domain, and only applies consent to users with an email address in that domain. So in order to grant Admin consent to act as user@example.com, the domain example.com must be claimed in your organization, and signature impersonation scopes must be granted under the Applications tab of DocuSign Administration (not DocuSign eSignature Administration).

Once the domain claim is confirmed, there can be a delay of a few minutes before it is recognized by DocuSign. If the error persists after that, we recommend clearing your browser cache.


Why am I getting UserNotFound when I make an UserInfo call with a valid token?

This is due to a known issue: API - UserInfo call returns empty array for specific user. Note that, while that article refers to an empty UserInfo response, the UserNotFound / "The user is not found in DocuSign" response is due to the same underlying behavior and has the same solution. Please open a DocuSign Support case referencing that article and providing the relevant information.


How do I fix an error with getting an auth token using the JWT flow?

Error Message: DocuSign.eSign.Client.ApiException: 'Error while requesting server, received a non successful HTTP code Error with response Body:'

Accompanied with this error is often one of three faults:

  • {Consent_Required}
    • Consent has been revoked
    • Consent has never been supplied
    • User / Consent is in a bad state, needs to be removed / reapplied

Please review the following for more information on Obtaining consent.

  • {Invalid_Grant}
    • The error description often reveals the source:
      • IAT (Timestamp the token is issued at) Is a time > 1 hour before the request is made
      • Exp (Expiration) value is in the past or before IAT time
    • RSA key is invalid
      • -----BEGIN RSA KEYPAIR----- / End lines removed
      • The PEM file has been corrupted
      • The RSA key is no longer properly registered within DocuSign and needs reissued
      • AUD line points to Demo over Prod or vice versa.
  • {Internal_Server_Error}
    • Invalid JWT assertion
    • RSA key is invalid
    • AUD parameter has an invalid value -- this value should specifically be account.docusign.com for Production, account-d.docusign.com for Demo. These values cannot containing a leading http://, https://, or trailing /
    • For example:
      • account-d.docusign.com = yes
      • https://account-d.docusign.com = no
      • account-d.docusign.com/ = no
      • ApiClient apiClient = new ApiClient("https://demo.docusign.net/restapi");
      • API Client being used needs to have calls pointed to {endpoint}.docusign.net/restapi

Please see the following on implementing JWT flow and assertion. Call the UserInfo endpoint to determine the base URI and account information to interact with the DocuSign API service.


When a user grants an individual OAuth consent or an organization administrator grants organization wide OAuth consent to your application, it never times out. The consent can be revoked however. The access token returned by DocuSign from a JWT flow expires in one hour. Attempting to set a longer expiry in the JWT assertion will have no effect on the token's lifespan. If your application uses the access token for multiple calls, you will need to store the expires in time and check the time before making API calls. The CheckToken() functions in our code examples demonstrate this.


Can OAuth tokens be revoked?

DocuSign OAuth tokens cannot be revoked. Revoking application consent will prevent new tokens from being generated, but will not invalidate existing tokens.


Why is my legacy header authentication failing when I enable two factor authentication (2FA)?

This is working as designed. Legacy header authentication and 2FA are mutually exclusive. Using an OAuth authentication flow will work with 2FA enabled.


While Admin Consent allows you to bypass the need for each individual user to provide consent, there are a couple of hurdles that must be cleared before you can successfully impersonate a user:

  1. The email domain of the user in question must be claimed by your organization in order for admin consent to apply. Subdomains are seen as distinct entities, so a user on an @mail.example.com email address won't automatically have consent granted when @example.com is claimed.
  2. The correct Scopes must be granted. Impersonation is always required for JWT authentication, signature covers the standard eSignature REST API, and other scopes are relevant to other functions.
  3. Admin Consent requires access to Organization functionality. If your account plan does not include this, reach out to your account team to discuss. For steps on how to claim a domain, see this guide.

    Does DocuSign RestApi support MASSL authentication?

    No, DocuSign does not support Mutual SSL Authentication.

    DocuSign supported SSL


    Templates

    Templates help streamline the sending process when you frequently send the same or similar documents, or send documents to the same group of people.


    Why aren't my template roles matching?

    For your template roles to match, the values that you supply for your routingOrder and roleName parameters must be identical to the role you're matching.


    What are some of the possible behaviors and issues during template matching?

    Scenario: Same role, different name

    Results:

    1. The ONESIGN_ALLSIGN_NOTSATISFIED API fault is returned if Document Visibility is enabled for a DS account.
    2. If Document Visibility is not enabled for the account, the envelope will be sent with duplicate recipients to the same email. One has tabs, the other does not.

    Scenario: Different role, same name or email

    Results:
    Error: Envelope contains duplicate recipients. This creates a new recipient with the same name, email, and signing order position as the original recipient. This often results in an error indicating the envelope contains duplicate recipients. In this situation, end users may see an error when working with tabs indicating that fields are out of sync.


    How to create and prefill tab values on a template?

    To supply a value for a tab on a template, you can supply the value alongside the tab's label within your tab definitions. See our setting template tab values code example.


    Envelope Management

    Envelope Management allows you to create, send, locate, track & manage envelopes in your account.


    Can the eSignature REST API override the account’s default reminders and expiration?

    Yes. When you create an envelope with the API, you can set how many days after send to begin reminding recipients and how often thereafter. You can also set when the envelope will expire, and how many days prior to expiration to warn the recipient. You can find a detailed explanation and code examples in several languages using our SDKs on the DocuSign blog.


    How can I avoid having my application throttled by DocuSign API rate limits?

    DocuSign has default rate limits of 1,000 API calls per hour, API burst limits of 500 calls in 30 seconds, and polling rules stating that GET calls to the same envelope resource may not be made more than once every 15 minutes.

    You can avoid rate limits by checking your API usage, using bulk operations, and refraining from requesting information more than once about envelopes in a terminal state (Completed, Voided, Declined). Instead of polling, we recommend using webhooks via DocuSign Connect. You do not need to change your firewall to use webhook notifications; see our blog post.

    You can find a detailed discussion of API rate limits and how to work more efficiently on our blog and guidance on general API resource limits on the Developer Center.

    Why are Anchor Strings are not applied if we use UpdateDocumentsAsync method?

    Anchor tag processing does not occur when additional documents are added to the envelope. You will need to either include all documents in the initial envelope creation call, or you will need to make an Envelopes::UpdateRecipients call with the desired tags once all documents have been applied to the envelope. If using the UpdateRecipient method to add tags, it is recommended that no tags be defined in the initial envelope creation call to prevent tags from being duplicated later in the workflow.


    How can I change a signing recipient to a carbon copy?

    For this task, the Envelopes::UpdateRecipients method should be used. For the call body, you would define a CarbonCopy recipient with the RecipientId of the signer you would like to change to a CC. No other parameters are necessary, and in fact may cause the change to fail. If the third recipient on an envelope has a RecipientId of "3", the call to change them to a Carbon Copy recipient would be a PUT to {{vx}}/accounts/{{account_id}}/envelopes/{{envelope_id}}/recipients with a body of

     

    {
      "carbonCopies": [
        {
          "recipientId": "3"
        }
      ]
    }

    Note that the UpdateRecipients method will return a '200 OK' response whether or not the change actually took effect. To confirm the update was successful, your application will need to parse the response body to look for a success or failure:

    {
      "recipientUpdateResults": [
        {
          "recipientId": "3",
          "errorDetails": {
            "errorCode": "SUCCESS",
            "message": ""
          }
        }
      ]
    }

    Note: Recipient role cannot be changed on completed envelopes.


    What are the file size limits for envelopes?

    We have a public-facing article outlining envelope file size limitations: https://support.docusign.com/en/articles/DocuSign-Document-and-Envelope-File-Size-Limitations

    Individual Document Packets (Or individual documents Uploads):

    These are limited to 25MB per packet, depending on the interface you're using. This limit is enforced at a platform level.

     


    How do I enable Responsive Signing?

    When attempting to use responsive signing features, you may see one of the following errors:

    • PLAN_ITEM_NOT_ENABLED
    • SMARTSECTIONS_NOT_ENABLED

    Responsive Signing currently comes enabled for all new developer sandbox accounts. In the event that you see the aforementioned errors, you will need to contact DocuSign Customer Support in order to have two features enabled:

    • Allow Recipients to Sign Responsive Documents
    • Enabled SmartSections/API for Responsive Signing

    If this is for a Production account, instead please visit our Contact Support Page and create a case to discuss enabling these features.


    How do I control envelope ID stamping through the API?

    For placing a tag that displays the envelope ID at a specific location:

    {
        "envelopeIdTabs":  [
                               {
                                   "tabLabel":  "EIDStamp",
                                   "conditionalParentLabel":  null,
                                   "conditionalParentValue":  null,
                                   "fontSize":  "size9",
                                   "underline":  false,
                                   "italic":  false,
                                   "fontColor":  "black",
                                   "bold":  false,
                                   "font":  "lucidaconsole",
                                   "pageNumber":  1,
                                   "documentId":  "1",
                                   "recipientId":  "86887495",
                                   "height":  14,
                                   "width":  66,
                                   "xPosition":  106,
                                   "yPosition":  235
                               }
                           ]
    }

    There are also two account level settings that can be altered by making a PUT to accounts/accountId/settings

    {
        "accountSettings":  [
                                {
                                    "name":  "enableEnvelopeStampingByAccountAdmin",
                                    "value":  "true"
                                },
    
                                {
                                    "name":  "envelopeStampingDefaultValue",
                                    "value":  "false"
                                }
                            ]
    }

    Lastly, there’s a third option to add / remove the envelopeId stamp in the create envelope or create template calls. This goes in the envelope definitions alongside the emailBlurb and emailSubject.

         "envelopeIdStamping":"true"
    

    How should my application poll for envelope status?

    In general DocuSign discourages polling to actively check for envelope status updates. That said, if DocuSign Connect cannot be used to monitor envelope status, polling for status may be a viable fall-back. The Envelopes::ListStatus method can be used to query several envelopes at once. By batching these status requests, an integration can reduce the volume of API traffic that is dedicated to polling.

    Polling for an envelope's status should not occur more than once every fifteen minutes (as per API Resource Limits), but for older envelopes it is often unnecessary to poll that frequently. As an envelope ages, it may be appropriate to reduce the rate of polling to once an hour or even once a day. Setting an appropriate expiration age on envelopes can prevent long-running envelopes from consuming API traffic.


    Why is my API call that references a template resulting in a recipient without tags? How do I resolve a "ONESIGNALLSIGN_NOT_SATISFIED - free form signing is not allowed" error when I've placed template tags for the recipient?

    Typically this is the result of a mismatch between the roles on the server template and the roles defined in the API call. To diagnose the issue, it is helpful to capture an API log to see exactly what is being sent to DocuSign. Common errors:

    • Trailing space in role name
    • Role Name must match exactly to map correctly
    • Mismatch in routing order defined in API call and on server template
    • If a custom routing order is to be defined in the API call, the 'change_routing_order=true' query string parameter should be defined. Otherwise, remove the RoutingOrder parameter from the API call.
    • If a routing order is not defined on the template, all recipients will have a routing order of "1".
    • Server template has pre-defined recipient name and email
    • An API call referencing a template cannot overwrite a predefined recipient. If the API call should be defining the recipient's name and email, the server template should leave the recipient's name and email blank so it can be used as a placeholder.

      Finally, it may be helpful to open the envelope for Correction to confirm if tags are present and assigned to the correct recipient. If tags appear when the envelope is Corrected, but not when the signer accesses the signer session, you may be trying to request a captive signing session for a remote recipient or otherwise accessing the envelope as the wrong recipient - checking the Envelope History will show who viewed the envelope at a particular time.


      How do I define witness recipients using the eSignature API?

      DocuSign eSignature provides the ability for a Signature to be witnessed. Using the eSignature REST API the signer must have the attribute "signWithWitness": true. The API can also suggest names and emails for the witness(es). Below is a JSON body that sends an envelope with a signer that requires a witness and suggests a witness name and email.

      {
          "documents": [
              {
                  "documentBase64": "BASE_64_OMITTED",
                  "documentId": "1",
                  "fileExtension": "pdf",
                  "name": "Test.pdf"
              }
          ],
          "emailSubject": "Witness Example",
          "recipients": {
              "signers": [
                  {
                      "email": "gxxxx@company.com",
                      "name": "Geoff Tester",
                      "signWithWitness": true,
                      "recipientId": "1",
                      "requireIdLookup": "false",
                      "routingOrder": "1",
                      "tabs": {
                          "signHereTabs": [
                              {
                                  "documentId": "1",
                                  "pageNumber": "1",
                                  "recipientId": "1",
                                  "xPosition": "100",
                                  "yPosition": "150"
                              }
                          ],
                      }
                  }
              ],
                  "witnesses": [
              {
                  "name": "Jane",
                  "email": "janexxxxx@company.com",
                  "roleName": "Witness 1 for Geoff",
                  "note": "",
                  "routingOrder": 1,
                  "status": "created",
                  "templateAccessCodeRequired": null,
                  "deliveryMethod": "email",
                  "witnessFor": "1",
                  "recipientId": "2",
                      "tabs": {
                          "signHereTabs": [
                              {
                                  "documentId": "1",
                                  "pageNumber": "1",
                                  "recipientId": "1",
                                  "xPosition": "200",
                                  "yPosition": "150"
                              }
                          ]
                      }
              }
              ]
          },
          "status": "sent"
      }

      How do I retrieve detailed envelope history or audit trail using the eSignature REST API?

      Use the listAuditEvents endpoint to get all the events of an envelope returned as an array of events, each event consisting of an array of name/value pairs. It is advisable to practice this call on a variety of test envelopes and examine the responses in order to know what events you are interested in retrieving for your application.


      How do I prevent recipients from reassigning envelopes through the eSignature REST API?

      Set the “allowReassign” envelope property to “false” in the envelopeDefinition object on your Create Envelope request.


      Why does the completed email not have the signed document when envelopes are created using eSignature REST API?

      This setting is configured in the DocuSign eSignature web application by navigating to Settings > Signing Settings > Envelope Delivery, and checking Attach documents to completion email.

      You must be an administrator in order to manage these settings.

      When selected, all the completed documents are included in the completed email sent to senders and signers as PDF file attachments.

      If you have confirmed that the account is properly configured, but documents are not attaching to the completion email, there may be another reason. See this article for reasons and solutions.


      Why are line breaks in HTML documents not honored on the completed PDF document?

      HTML documents that are uploaded via the eSignature web application or the API using the standard document property support setting line breaks with the following inline CSS:

      <div style="page-break-before:always">&nbsp;</div>

      Responsive HTML Documents uploaded via the API do not support page breaks. The point of responsive documents is to display properly on any device, regardless of size.

      If a new page is desired on all devices, then you can upload separate html documents and when converted to PDF they will appear as separate pages.


      How do I send an envelope on behalf of another user?

      DocuSign supports different types of OAuth. While each OAuth type does function slightly differently, the following configurations allow for Send On Behalf Of functionality:

      Authorization Code Grants are ideal for ISVs, as the user they send on behalf of is required to be present and enter their login credentials.

      JSON Web Tokens do not require a user to be present, but they do require that the user you wish to send as provides their consent for you to do so. Once consent has been supplied, you can generate new OAuth tokens on the behalf of that user. When you use that same token to send an envelope, you will be authenticated and send the envelope as said user. Please see the following articles for more information:

      Authorization Code Grant
      OAuth JWT: Granting Consent


      How do I create radio buttons using the API?

      In order to place Radio Group tabs via an API call, there are two sections: Radio Group Tab definitions and Radio Group Buttons.

      The radio group definitions include the document ID, recipient ID, the name of the Radio Group, and whether or not the group is required.

      The buttons themselves are added individually to the array of Radio Group buttons. The definitions for each button should contain either an anchor string, or a page number, xPosition, and yPosition. Optionally you can also supply additional parameters such as font size, font color, italicize, and bolding effects.

      Radio group & Tab definition:

      	Radio Group Tabs:
      		Document Id
      		RecipientId
      		Group Name
      		shared
      		requiredInitialOnSharedChange
      		requireAll
      		tooltip
      		tabType (radiogroup)
      		Radio Group Buttons >
      			Button 1>
      				PageNumber
      				xPosition
      				yPosition
      				value
      				selected (true/false)
      				locked
      				tabOrder
      			Button 2>
      				PageNumber
      				xPosition
      				yPosition
      				value
      				selected (true/false)
      				locked
      				tabOrder
      			Button 3>
      				PageNumber
      				xPosition
      				yPosition
      				value
      				selected (true/false)
      				locked
      				tabOrder
      
      "tabs": {
      		"radioGroupTabs": [
      			{
      				"documentId": "1",
      				"recipientId": "33160812",
      				"templateLocked": "false",
      				"templateRequired": "false",
      				"groupName": "Radio Group 1",
      				"radios": [
      					{
      						"pageNumber": "1",
      						"xPosition": "51",
      						"yPosition": "176",
      						"value": "Radio_1_3",
      						"selected": "false",
      						"tabId": "9e7822b3-7c0f-47cc-8bc8-774ee53b36cd",
      						"required": "true",
      						"locked": "false",
      						"tabOrder": "3",
      						"font": "lucidaconsole",
      						"bold": "false",
      						"italic": "false",
      						"underline": "false",
      						"fontColor": "black",
      						"fontSize": "size9"
      					},
      					{
      						"pageNumber": "1",
      						"xPosition": "51",
      						"yPosition": "137",
      						"value": "Radio_1_1",
      						"selected": "false",
      						"tabId": "ecb8c6b8-9a17-4f03-9053-94d6a6264606",
      						"required": "true",
      						"locked": "false",
      						"tabOrder": "1",
      						"font": "lucidaconsole",
      						"bold": "false",
      						"italic": "false",
      						"underline": "false",
      						"fontColor": "black",
      						"fontSize": "size9"
      					},
      					{
      						"pageNumber": "1",
      						"xPosition": "51",
      						"yPosition": "157",
      						"value": "Radio_1_2",
      						"selected": "false",
      						"tabId": "33adf214-9523-464e-a2f3-43d3a9789e65",
      						"required": "true",
      						"locked": "false",
      						"tabOrder": "2",
      						"font": "lucidaconsole",
      						"bold": "false",
      						"italic": "false",
      						"underline": "false",
      						"fontColor": "black",
      						"fontSize": "size9"
      					},
      					{
      						"pageNumber": "1",
      						"xPosition": "51",
      						"yPosition": "195",
      						"value": "Radio_1_4",
      						"selected": "false",
      						"tabId": "207d45f2-2c94-4c5d-93e6-32c11f7e6e09",
      						"required": "true",
      						"locked": "false",
      						"tabOrder": "4",
      						"font": "lucidaconsole",
      						"bold": "false",
      						"italic": "false",
      						"underline": "false",
      						"fontColor": "black",
      						"fontSize": "size9"
      					}
      				],
      				"shared": "false",
      				"requireInitialOnSharedChange": "false",
      				"requireAll": "false",
      				"tooltip": "Test Radio Group 1 Tooltip",
      				"tabType": "radiogroup"
      			}
      		]
      	}
      

      How do I change embedded signers to remote signers and vice versa using the API?

      When shifting recipients between embedded and remote signing, the key component is the clientUserId.

      To shift a remote signer to become an embedded signer, you will need to update your recipient definitions to include a clientUserId with a non-blank/null value. For example, PowerForms use a clientUserId equal to the recipient’s email address.

      To shift from an embedded to remote signer, you will need to update your recipient definitions to include a clientUserId with a value of “”. If the clientUserId is not specified as blank, it is ignored and the recipient does not shift to captive.