From the Trenches: Track your templates with Envelope Custom Fields
Developer Support has worked with several customers over the past few months who are running into API rate limits due to heavy reliance on the API call to find the templates associated with a given envelope. By default, Docusign Connect does not return information about what templates were used to generate an envelope. Developers who iterate through their envelopes to find the templates can end up making thousands of GET calls in an hour and running into hourly rate limits.
The solution is to take advantage of Envelope Custom Fields. Envelope Custom Fields let you store metadata in your envelopes that is not visible to the signer. Let’s take the simplest use case first. Users are sending envelopes using one Docusign template from the Docusign eSignature application. First create an Envelope Custom Field named TemplateID. Then you can save the value of the template in that field on your template.
Envelopes sent with this template would now return the following in the Connect:
<CustomField>
<Name>TemplateID</Name>
<Show>False</Show>
<Required>False</Required>
<Value>ce839909-xxxx-xxxx-xxxx-a05dbd8c7217</Value>
</CustomField>
Alternatively, you could get all the envelopes sent using this template since a given date in a single API call to listStatusChanges.
Using the API to send envelopes with multiple templates
A more complex, but quite common, use case is using Docusign’s Composite Template model to send envelopes using multiple templates. If we are inattentive, we could easily overwrite the value of the TemplateID Envelope Custom Field with each template we use in the envelope. So here we either need more Envelope Custom Fields, Temp1, Temp2 etc or we can write a comma delimited list to our TemplateID field. When using CompositeTemplates, the Envelope Custom Fields must be added in the inlineTemplate. Since last in wins, the inlineTemplate in your last composite template should write the values.
In the JSON example below, I am sending an envelope with two templates and writing the values for both templateIds to the TemplateID field.
{
"emailBlurb": "Please review and sign your documents",
"emailSubject": "Your application is ready to be signed.",
"brandId": "d4177ebe-xxxx-xxxx-xxxx-1e6c2b45cf2b",
"notification": {
"useAccountDefaults": "true"
},
"compositeTemplates": [
{
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "test...@gmail.com",
"name": "My Customer",
"recipientId": "1",
"tabs": {
"signHereTabs": [
{
"documentId": "1",
"pageNumber": "1",
"recipientId": "1",
"xPosition": "111",
"yPosition": "93"
}
]
}
}
]
}
}
],
"serverTemplates": [{
"sequence": "1",
"templateId": "ce839909-xxxx-xxxx-xxxx-a05dbd8c7217"
}]
},
{
"inlineTemplates": [
{
"sequence": "2",
"customFields": {
"textCustomFields": [
{
"name": "TemplateID",
"value": "ce839909-xxxx-xxxx-xxxx-a05dbd8c7217,d1e1d393-xxxx-xxxx-xxxx-2cea9bf6ab88"
}
]
},
"recipients": {
"signers": [
{
"email": "test...@gmail.com",
"name": "My Customer",
"recipientId": "1",
"tabs": {
"signHereTabs": [
{
"documentId": "1",
"pageNumber": "1",
"recipientId": "1",
"xPosition": "111",
"yPosition": "93"
}
]
}
}
]
}
}
],
"serverTemplates": [{
"sequence": "1",
"templateId": "d1e1d393-xxxx-xxxx-xxxx-2cea9bf6ab88"
}]
}
],
"status": "sent"
}
The resulting Connect request includes both templateIds.
<CustomField>
<Name>TemplateID</Name>
<Show>False</Show>
<Required>False</Required>
<Value>
ce839909-xxxx-xxxx-xxxx-a05dbd8c7217,d1e1d393--xxxx-xxxx-2cea9bf6ab88
</Value>
</CustomField>
Architectural considerations
When planning your integration, you will need to consider what Envelope Custom Fields to deploy in your Docusign account and think through the scenarios when you want to write values or retrieve values from these fields. Docusign Professional Services can help you think through your use cases and plan your integration accordingly. You can engage Professional Services through your Docusign account manager.
