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

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:

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

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

My first document has:

While my second has:

So, despite the document IDs changing and the file names being the same, I can still tell them apart. the 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 parameter. Both recipient custom fields and the are readily available in the Recipients::List call or in a Envelope::Get call with . If you're already referencing a server template, continuing to use the to identify a particular recipient is likely the simplest way to move forward, but if you need multiple data points or the 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.