DocuSign Developer FAQs - Templates, Envelopes, and Connect

DocuSign Developer FAQs ‐ Templates, Envelope Management, and Connect

The following are answers to some of the most common questions we receive about Templates, Envelope Management, and Connect. 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.


Templates


Envelope Management


Connect


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.


    Why am I receiving an "EnvelopeSends call blocked" error?

    An error 400 with an error message of {"errorCode":"UNSPECIFIED_ERROR","message":"EnvelopeSends call blocked"} means that you have exceeded your account's monthly envelope limit. You'll either need to upgrade your account plan to allow more sent envelopes, or wait for your monthly usage to reset.


    How do I edit email messages using the eSignature REST API?

    To change the email subject and message of a draft envelope, include the following code in the request body:

    {
      "emailSubject": "new email subject",
      "emailBlurb": "new email message"
    }

    For additional information please see the Envelopes: update reference page.


    How do I define the recipient language using the eSignature REST API?

    If your account has Sending Settings > Enable custom email and language for each recipient checked, you can define the language by using the EmailNotification > SupportedLanguage parameter in the recipient definition. For more information on the EmailNotification parameter, see From the Trenches: Recipient Email Languages.

    1. Note that the language defined in the API call will only apply to users who do not have a DocuSign account and who have not interacted with DocuSign in the past. In the event that a recipient has used DocuSign previously, their language preferences will override what is in the API call.
    2. If the recipient has an account, they can set their language by navigating to My Preferences > Regional Settings. If the recipient does not have an account, the language displayed is based on their browser/operating system preferences, but can be changed by using the Language dropdown in the corner of a signing session.

    How do I enable "Allow Signer Reassign" on an envelope using the eSignature REST API?

    Set the "allowReassign" parameter to “true” in the create envelope request. For additional information please see the Envelopes: create reference page.


    Connect

    DocuSign Connect is a push service that sends real-time data updates to external applications.


    How do I resolve a "remote server refused connection" error in Connect?

    The error message displayed in the Connect failure log is the response from the uri that has been provided via your Connect objects. A few potential points of failure could be:

    1. The URI is invalid. Make sure to double check your Connect object to ensure there are no typos in the “URL To Publish” section of your Connect object. The required protocol for the URI is https.
    2. The server housing the listener has rejected the connection attempt. This most commonly happens when the IP ranges for DocuSign Connect have not been added to the allowlist on the server’s firewall. Please see IP Range List for more details.
    3. Most often, if a listener is unable to process a payload you will receive a message stating that a 500 (Internal Server) error has occurred. In some cases, this situation will also result in a refused connection. The best practice is to update the listener’s XML Schema: https://www.docusign.net/api/3.0/schema/dsx.xsd ‐ specifically the EnvelopeStatus and DocumentPDF objects. You may also want to check your listener to ensure that it can receive files over a certain size. DocuSign PDFs can range from a few KB to 25+MB. Your listener will need to handle the full spectrum.

    Does DocuSign Connect support JSON data or payloads?

    Yes, however you cannot toggle an existing DocuSign Connect configuration to use JSON payloads. You can create a new configuration and choose the REST v2.1 Data Format to make Connect send JSON payloads. For details see Data format: Legacy vs. REST v2.1 format.

    You can also specify JSON payloads using the eventNotification by adding the eventData attribute.

    	"eventNotification": {
    	"eventData": {
            "version": "restv2.1",
            "format": "json", 
            "includeData":  ["tabs","recipients"]
        },

    References