From the Trenches: How to track recipients and documents when IDs change

•

Summary•3 min read

Developers can use the eSignature REST API to set custom fields to track recipients and documents across composite templates.

Additional resources

Additional resources

One thing you may notice if you are moving from a simple envelope workflow to a composite template model is that some values don't stay consistent from the envelope definition to the envelope itself. Specifically, document IDs and recipient IDs only hold true within each individual composite template.

From a technical perspective, this is necessary because an envelope can have multiple composite templates—potentially including the same server template multiple times—and they all need to be able to merge together without conflict. In practice, this means that you need to use other means than the ID to identify a specific recipient or document in later calls against an envelope.

The file name is generally a good identifier for a particular document, but document custom fields (not to be confused with tabs) can be used as well. For example, say I'm adding this document to my composite template call:

"document": {
  "documentBase64": "ZXhhbXBsZSB0ZXh0IFxzMVwNCmV4YW1wbGUgdGV4dCB0d28gXHMyXA==",
  "documentId": 99,
  "name": "example.txt",
  "fileExtension": "txt",
  "documentFields": [
    {
      "name": "CustomName",
      "value": "Example Value"
    }
  ]
}

When I need to check later which documents were included in the envelope, my documentId has changed and my file name might not be descriptive enough, but I can still pull those document fields to see that my CustomName field is set to "Example Value", enabling me to identify the document. To do so, I'll first pull the list of documents:

[[some data redacted for brevity]]
  "envelopeDocuments": [
    {
      "documentId": "1",
      "name": "example.txt",
      "type": "content",
      "order": "1",
    },
    {
      "documentId": "2",
      "name": "example.txt",
      "type": "content",
      "order": "1",
    },
    {
      "documentId": "certificate",
      "name": "Summary",
      "type": "summary",
      "order": "999",
    }

Since the filenames are the same, I'll check the fields for my two documents using the EnvelopeDocumentFields::List call.

My first document has:

{
  "documentFields": [
    {
      "name": "CustomName",
      "value": "Example Value"
    }
  ]
}

While my second has:

{
  "documentFields": [
    {
      "name": "CustomName",
      "value": "Second Document"
    }
  ]
}

So, despite the document IDs changing and the file names being the same, I can still tell them apart. the documentFields property is also available through Connect, so downstream processing can take advantage of them.

With recipients, you have an extra option in addition to recipient custom fields: the RoleName parameter. Both recipient custom fields and the RoleName are readily available in the Recipients::List call or in a Envelope::Get call with include=recipients. If you're already referencing a server template, continuing to use the RoleName to identify a particular recipient is likely the simplest way to move forward, but if you need multiple data points or the RoleName isn't right for your use case, you can use recipient custom fields instead.

Long story short: When sending with composite templates, document IDs and recipient IDs are only consistent within each individual composite template of the envelope creation call: once the envelope is generated, they'll be renumbered and you'll need to use other means to identify individual documents and recipients.