Skip to main content
Blog
Home/

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

Author Drew Martin
Drew MartinDeveloper Support Engineer
Summary3 min read

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

    • Additional resources

    Table of contents

    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.

    Additional resources

    Author Drew Martin
    Drew MartinDeveloper Support Engineer
    More posts from this author

    Related posts

    • Trending Topics: Latest from our forums (November 2024)
      Developer Trending Topics
      Author Paige Rossi
      Paige Rossi
    • Leveraging Docusign AI and Salesforce for Improved Contract Management

      Leveraging Docusign AI and Salesforce for Improved Contract Management

      Author Subbarao Pydikondala
      Subbarao Pydikondala
    Trending Topics: Latest from our forums (November 2024)
    Author Paige Rossi
    Paige Rossi
    Leveraging Docusign AI and Salesforce for Improved Contract Management

    Leveraging Docusign AI and Salesforce for Improved Contract Management

    Author Subbarao Pydikondala
    Subbarao Pydikondala

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting