Docusign REST API: template roles for sent envelope

Question

So I am currently using the Docusign API to build a web app that involves having users signed a shared document, and everything works fine in a normal scenario: a template will be created and have predefined roles like "signer 1", "signer 2", "special 1"; when a signing happens, an envelope will be created from the template have users associated with roles, like user1 with signer 1, user 2 with signer 2, and users can sign the tabs that are associated with their roles.

However, there are some scenarios that I need to modify the users signing the sent envelope. For example, I might need user 2 to switch from the role "signer 2" to "special 1", therefore I will first remove user 2 from the recipients, and add user 2 with the role "special 1" back in the recipients. Ideally, the tabs that are associated with "special 1" as defined in the template should now be user 2's duty to sign. However, when user 2 is added back in, it is not linked with the tabs defined for the role "special 1", though in the envelope status it shows that user 2 has the role "special 1".

Does anyone know what's happening here? My suspect is that template roles are only applied when the envelope is first created, the later-added recipients, though set with rolename, does not take the role that was defined in the template. If my guess is correct, are there any ways to solve this issue?

Any help will be greatly appreciated.

Answer 1

Your assumption is correct -- i.e., template roles (and corresponding tabs) are assigned during envelope creation only. If you subsequently add recipient(s) for the envelope, they'll never automatically have tabs -- even if you assign them to a role that the original template specifies tabs for.

Here's a potential work-around for you:

• In the Template, specify a total of 4 roles: 1- signer1; 2- placeholder; 3- signer2; 4- special1 Make sure to specify all of the tabs you want recipient roles 1, 3, and 4 to have, and just specify a single "sign here" tab for the placeholder recipient role.

• When you create the envelope, specify recipient info for all 4 roles. For the "placeholder" role, it doesn't really matter what name/email you specify -- this recipient role is simply there to pause the envelope temporarily, until you know which role the second recipient should occupy. For both the "signer2" role and "special1" role, specify recipient #2's name and email address. (Note: In your "Create Envelope" API call, you'll need to set the allowRecipientRecursion property to true so that duplicate recipients are allowed.)

• When the first recipient completes signing, the envelope will advance to the next recipient in the workflow (placeholder role). Since this "placeholder" recipient doesn't correspond to a real person, the Envelope will sit there in the routing order until this recipient is removed from the Envelope.

• Once you know which role the second recipient needs to occupy ("signer2" or "special1"): 1-Programmatically delete the recipient corresponding to the un-needed role ("signer2" or "special1"), and 2-Programmatically delete the recipient that corresponds to the "placeholder" role. This will result in the Envelope having only 2 remaining recipients ("signer1" and either "signer2" or "special1"); the envelope workflow will automatically advance to the last (i.e., second) recipient as soon as you delete the "placeholder" recipient from the envelope -- and that recipient will get all the tabs that the Template defined for that role.