From the Trenches: Routing out of order

•

Summary•3 min read

Best practices for updating recipients’ routing order when using templates with the Docusign eSignature REST API.

The Standard Case
What can go wrong?
Additional resources

The Standard Case
What can go wrong?
Additional resources

When referencing a template through the Docusign eSignature REST API, it's generally a good practice to leave the routing order out of your TemplateRole definition to ensure that whatever is in the server template is honored and everything simply aligns. That said, there are cases when it is appropriate to change the routing order for a specific envelope.

If not done correctly, this will result in a role mismatch, and template tabs lost. The following holds true whether you are using a single template with one or two signers, or a composite template workflow with several recipients.

The Standard Case

Most commonly, the server template's routing order is correct. When this is the case, the recipient definition in the API call should reference the template's role name. The routing order parameter must either match the template or not be present in the API call.

Keep in mind that all templates do technically have a routing order: If the routing order is "disabled" in the web console, all template roles will have a routing order of "1".

Changing the Routing Order

If the server template's routing order isn't appropriate for a particular envelope, the change_routing_order=true query string parameter can be used. With that in place, the role name will still be used to match recipients to roles, but the routing order from the API call will take effect. To use that parameter with one of the Docusign client libraries, a CreateEnvelopesOptions object should be created with the change routing order parameter set to true.

If you are calling the raw API, this means modifying the URL to POST {{vx}}/accounts/{{account_id}}/envelopes?change_routing_order=true

In the C# library, this would look like:

         EnvelopesApi.CreateEnvelopeOptions createEnvelopeOptions = new EnvelopesApi.CreateEnvelopeOptions()
         {
             changeRoutingOrder = "true"
         };
         envelopesApi.CreateEnvelope(accountId, envelopeDefinition, createEnvelopeOptions);

What can go wrong?

If change_routing_order is not defined for the API call and the routing order defined in the API call does not match the order in the server template, the role will not map correctly. Typically this results in the recipient being sent an envelope without tags, leading to a "free form signing" experience.

As always, we recommend frequent testing in the Demo environment and confirm everything aligns, and especially when implementing a new workflow.