Here is what I am trying to do.
I create a docusign template by calling their rest api. In that call I specify 2 signers with
"signers": [
{ "RecipientId": 1, "RoleName": "role1", "routingOrder": 1 },
{ "RecipientId": 2, "RoleName": "role2", "routingOrder": 2 }
]
Then I generate sender view url and redirect to that url. In docusign, i see recipients being populated correctly.
I add 2 sign here tabs.
I assign one signhere to role1, and the other to role2.
Then I make call for generating recipient url, but just can't get it right.
How can I get recipient view url by providing recipient id or role?
I keep getting the following response.
{
"errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
"message": "The recipient you have identified is not a valid recipient of the
specified envelope."
}
Here is my request body
{
"returnUrl": "hidden",
"clientUserId": 1,
"recipientId": 1,
"UserName": "role1",
"Email": "fake#test.com",
"AuthenticationMethod": "Email"
}
Unfortunately we don't support changing the routing order when populating the role attributes. Instead you need to change the recipients explicitly.
Related
When using agents/intermediaries to assign signers in DocuSign, we set the clientUserId for the signers to use the embedded signing feature. But DocuSign will automatically send out the email to the assigned signers and we are not able to obtain the signing URL through the API POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/views/recipient.
As suggested in this thread: https://stackoverflow.com/a/63810135/13191875 . It's due to the clientUserId was removed when agents/intermediaries change the signer's email/name info. It suggests that a workflow could be added to pause the process after the signer's email/name info is changed, and then add the clientUserId to the signer, then resume the workflow.
I tried with request body:
{
"recipients": {
"intermediaries": [
{
"clientUserId": "1",
"email": "aaa#example.com.au",
"name": "Intermediary",
"recipientId": "1",
"routingOrder": "1"
}
],
"signers": [
{
"clientUserId": "2",
"email": "example#example.com",
"name": "example",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorIgnoreIfNotPresent": "false",
"anchorString": "Signature_anchor_1",
"anchorUnits": "pixels",
"anchorYOffset": "0",
"name": "Please sign here",
"recipientId": "1"
}
]
}
}
]
},
"workflow": {
"workflowSteps": [
{
"action": "pause_before",
"itemId": "2",
"triggerOnItem": "routing_order"
}
]
},
"emailSubject": "DocuSign API - Signature Request on Document Call",
"documents": [
{
"documentId": "1",
"name": "{{fileName}}",
"documentBase64": "{{fileBase64}}"
}
],
"status": "sent"
}
I can set the clientUserId after the signer's email/name is changed. But the workflow cannot be resumed by calling the API PUT {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}?resend_envelope=true. So the signer's signing URL cannot be obtained since the process is paused, the signer's status stays in created.
I also tried the with agents:
{
"recipients": {
"agents": [
{
"clientUserId": "1",
"email": "aaa#example.com.au",
"name": "Agent",
"recipientId": "1",
"routingOrder": "1"
}
],
"signers": [
{
"clientUserId": "2",
"email": "",
"name": "",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorIgnoreIfNotPresent": "false",
"anchorString": "Signature_anchor_1",
"anchorUnits": "pixels",
"anchorYOffset": "0",
"name": "Please sign here",
"recipientId": "1"
}
]
}
}
]
},
"workflow": {
"workflowSteps": [
{
"action": "pause_before",
"itemId": "2",
"triggerOnItem": "routing_order"
}
]
},
"emailSubject": "DocuSign API - Signature Request on Document Call",
"documents": [
{
"documentId": "1",
"name": "{{fileName}}",
"documentBase64": "{{fileBase64}}"
}
],
"status": "sent"
}
After the name/email is added by the agent, the process is paused and I set the clientUserId for the signer, I verified that it is added by calling the get recipients info API. After I resume the process, an email is sent by DocuSign to the signer and I cannot get the embedded signing URL for that signer. I can see the clientUserId is removed for that signer by calling the get recipients info API again.
My question is:
when using agents/intermediaries in DocuSign, is it possible that we can obtain the embedded signing URL for the assigned signer whose email is updated/added by agents/intermediaries?
when using agents/intermediaries in DocuSign, is it possible that we can turn off that email from DocuSign to the signer, whose email is updated/added by agents/intermediaries?
when using agents/intermediaries in DocuSign, is it possible that we can obtain the embedded signing URL for the assigned signer whose email is updated/added by agents/intermediaries?
Yes, but you'll first need to assign a clientUserId to the recipient.
And since the recipient has already been sent an email invite to the signing ceremony, adding a clientUserId attribute is problematic since doing so will invalidate the email invite.
when using agents/intermediaries in DocuSign, is it possible that we can turn off that email from DocuSign to the signer, whose email is updated/added by agents/intermediaries?
To do this, you need to stop the workflow as I described in the other answer.
Much better would be to expand your API application so that it is used to change the name/email of the signer. That way your application can also set the clientUserId at the same time and the signer won't receive any email.
Basically, embedded signing is only intended to work if the envelope is created/edited via an API program. Your goal of using an API program and using the regular DocuSign Web App (which focuses on email delivery, not embedded signing) is mixing apples and oranges. It is possible but problematic.
You can potentially use the new Advanced Recipient Routing (ARR) feature to pause the envelope, obtain the information about the next recipient (via GET call to listRecipients) and then modify it to add the clientUserId. I have not tried this, but in theory that should work.
ARR is now available in demo/developer accounts for all new accounts created.
https://developers.docusign.com/docs/esign-rest-api/how-to/pause-workflow has information about how to create the envelope such that it pauses after a specific routing number.
https://developers.docusign.com/docs/esign-rest-api/how-to/unpause-workflow shows how to resume the envelope once you made your change.
The other thing you may need to do is add a webhook call for when the status of the intermediary was updated so you know when to update the next recipient (but before you can do that you would have to obtain the information about the new recipient).
I am trying to send a DocuSign envelope, that has already been sent to a customer (not signed yet), to another or a new customer. This is slightly different from resending the contract, but the same envelope is being resent to a new contact.
Is this possible? I have tried all sorts of things, like change the recipient details to new contact, add new sender to the existing recipient details.
The document is sent to the original sender fine, but to the new sender, the tab information is missing and the sign here tab is not there.
Replacing the original recipient :
The original recipient can be replaced with a new recipient using the UpdateEnvelopeRecipients api.
The original recipient will no longer have access to the envelope.
PUT /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients
{
"signers": [
{
"recipientId": 1,
"email": "newsigner#acme.com",
"name": "New Signer",
}
]
}
Adding a new recipient: To add a new recipient in addition to the existing recipients, use the CreateEnvelopeRecipients api.
POST /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients
{
"signers": [
{
"recipientId": 2,
"email": "newsigner#acme.com",
"name": "New Signer"
}
]
}
To Add tabs to the new recipient, use the CreateEnvelopeRecipientTabs api. Make sure you specify the recipientId correctly in the Url.
POST /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs
{
"signHereTabs": [
{
"documentId": "1",
"pageNumber": "1",
"xPosition": "120",
"yPosition": "120",
}
]
}
We can generate multiple Remote Signers web request and keep all the signatures from Remote signers on the same document based on the workflow and Routing Order.
The main challenge we are facing is:
If we have multiple Embedded signers and Remote signers on the same document.
How can we send the setup the web service request so that all the Signatures are captured on the same document.
Seems like for each Embedded signer an unique signing URLs is generated.
Is there a way we can maintain the same envelop for all the signers?
Please advise.
Thank you
Sure, that's easy. For any recipient who will sign through Embedded Signing you need to set their clientUserId property when you add them to the envelope. For remote signers simply do not include this property at all in those recipients' definitions.
To control the order of signing use the routingOrder property for each recipient. Note that you can only generate a signing URL for a recipient when it is their turn in the routing order, and that both serial and parallel routing is supported by the DocuSign platform.
For example, to have 3 people sign in order where the first and third recipients sign through embedded signing and the second is a remote signer - i.e. initiates through an email notification - you could use this JSON:
{
"status": "sent",
"emailSubject": "Embedded and Remote Signers",
"documents": [{
"documentId": "1",
"name": "contract.pdf",
"documentBase64": "base64 document bytes...",
}],
"recipients": {
"signers": [
{
"email": "john#email.com",
"name": "John Doe",
"recipientId": "1",
"routingOrder": "1",
"clientUserId": "1001"
},
{
"email": "sally#email.com",
"name": "Sally Doe",
"recipientId": "2",
"routingOrder": "2"
},
{
"email": "bob#email.com",
"name": "Bob Doe",
"recipientId": "3",
"routingOrder": "3",
"clientUserId": "1002"
}
]
}
}
Using the docusign rest api i would like to create an envelope with 2 documents.
I will then be using the Post Recipient view to show document 1 to the first recipient (in an iframe) and once signed show document 2 in the same envelope to another recipients.
i have created the templates with different tempalteRoles (different names, order 5 and 10).
Its my understanding using a userId and the right settings in my docusign account, i can show document 1 to recipient 1 and then document 2 to recipient 2.
When i try and create the composite envelope the whole document is shown.
when i call the recipient status for the envelope it only shows one signer.
I have found the envelope will only create when the 2 template roles have the same clientUserId, userName and email, otherwise i get the error "ONESIGNALLSIGN_NOT_SATISFIED"
here is the envelope i am sending through
{
"accountId": "ACCOUNT_ID",
"emailSubject": "Email subject",
"status": "sent",
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"roleName": "PDS Customer",
"email": "pds#example.com",
"name": "TestFirstName TestSurname",
"clientUserId": "1",
"tabs": {
"textTabs": [
{
"tabLabel": "DocumentNumber",
"value": "123456789",
"locked": true,
"documentId": 1,
"pageNumber": 1
}
...removed some
]
}
},
{
"roleName": "Customer",
"email": "test#example.com",
"name": "mrTestFirstName TestSurname",
"clientUserId": "2",
"tabs": {
"textTabs": [
{
"tabLabel": "StorerEmail_LocalPart",
"value": "test",
"locked": true,
"documentId": 2,
"pageNumber": 1
}
...removed some
]
}
}
],
"compositeTemplates": [
{
"compositeTemplateId": 1,
"serverTemplates": [
{
"sequence": 1,
"templateId": "TEMPLATE_ID_2"
}
]
}
]
}
The error message is due to having Document Visibility enabled. In that scenario, each signer must have at least one tab present. Your second signer (embedded or not) must have at least one tab. In this case it'd probably be on the second document.
Your API call above does refer to a second documentId though so you may be okay there.
I would suggest that you not mix the "simple" sending (using templateRoles at the top level) with composite templates. Instead, add an inline template to the compositeTemplates structure with all of your recipient information. You may be seeing some odd behavior due to mixing those.
Lastly, the default Document Visibility configuration will show a document to a recipient only if they have a tab on that document. If your second signer should see all documents then you must either add a tab for them on each document or explicitly set visibility per document.
I am creating composite templates that work correctly and I'm running into this issue.
I am adding 2 templates to sign via docusign. I set the routing orders for both of them as shown below:
Form 1
Order 1 RoleName signer test1#gmail.com
Order 2 RoleName signer2 test2#gmail.com
Form 2
Order 1 RoleName dataEntry test1#gmail.com
Order 2 RoleName dataEntry2 test2#gmail.com
This will send one email to test#gmail.com. This user completes all of his fields for both Form 1 and Form 2 in one request. This is what I want and expect. However, when test1#gmail.com completes their process, test2#gmail.com will receive 2 different emails. One to sign form 1 and the other to sign form 2. I'm trying to understand why test2#gmail.com doesn't work the same as test1#gmail.com. Can someone help explain what the reason is for receiving 2 separate emails for test2#gmail.com may be and if there's a way to fix it?
Note: When I do this via the docuSign website, it doesn't allow for the same recipient to be in that same routingOrder. It will bring up the error:
The role 'signer' conflicts with 'dataEntry'
The role 'signer2' conflicts with 'dataEntry2'
This behavior seemed strange to me since I'm able to send the envelope using the docusign rest API. If somebody could give me some clarification on this as well I'd appreciate it.
Thank you!
I am unable to repro the issue you describe. Here's what I did, and the Result:
I created two separate templates in DocuSign, each having a single document and two recipients/signers (with Role Names and Routing Orders that you specify above in your question).
I used the REST API (JSON request included below) to create/send an Envelope from these two Templates, specifying identical recipient information (name/email/recipient ID/routing order) for Recipient 1 and Recipient 2 across both Inline Template structures.
Result: Recipient 1 receives an email first, opens the envelope, and signs both documents at once. Then Recipient 2 receives an email, opens the envelope, and signs both documents at once. The Envelope status is "Completed" at that point.
I've included my API request below for your reference -- perhaps compare/contrast this with what you're doing? Also -- make sure that Recipient information (Name / Email / Recipient ID / Routing Order) is identical (including case) for each recipient between the first Inline Template and the second Inline template within the API Request -- any small difference in Name/Email/Recipient Id/Routing Order, and DocuSign will treat them as different/separate people (recipients).
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"emailSubject": "Please sign",
"emailBlurb": "Please sign...thanks!",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence" : 1,
"templateId": "TEMPLATE_ID_1"
}],
"inlineTemplates": [
{
"sequence" : 2,
"recipients": {
"signers" : [{
"email": "adamsemail#outlook.com",
"name": "Adam Adamson",
"recipientId": "1",
"roleName": "signer",
"routingOrder": "1"
},
{
"email": "bobsemail#outlook.com",
"name": "Bob Burns",
"recipientId": "2",
"roleName": "signer2",
"routingOrder": "2"
}
]
}
}]
},
{
"serverTemplates": [
{
"sequence" : 1,
"templateId": "TEMPLATE_ID_2"
}],
"inlineTemplates": [
{
"sequence" : 2,
"recipients": {
"signers" : [{
"email": "adamsemail#outlook.com",
"name": "Adam Adamson",
"recipientId": "1",
"roleName": "dataEntry",
"routingOrder": "1"
},
{
"email": "bobsemail#outlook.com",
"name": "Bob Burns",
"recipientId": "2",
"roleName": "dataEntry2",
"routingOrder": "2"
}
]
}
}]
}]
}