I can create an envelope with recipients with tabs. I can also create an envelope, add additional recipients, then add tabs to those recipients. This takes two requests, (1) add recipient, (2) add tab to recipient. I can't get Docusign to add a recipient and tabs dynamically in one call. I've started by trying to get it to work using the REST API Explorer:
PostEnvelopeRecipients
Which results in the following request:
{
"signers": [
{
"clientUserId": "1234",
"email": "testuser6#example.com",
"name": "tab testuser6",
"recipientId": "1234",
"tabs": {
"signHereTabs": [
{
"documentId": "1",
"pageNumber": "1",
"xPosition": "200",
"yPosition": "200"
}
]
}
}
]
}
This results in a recipient being added to the envelope properly, however it does not have any tabs. How can I add tabs when creating a recipient after the envelope is already created in one call?
It is not possible to add Tabs using the PostEnvelopeRecipients or PutEnvelopeRecipients api. After an envelope is created/sent, two separate calls are required to add recipients and tabs.
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).
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.
I'm using DocuSign's rest API to add recipient signing tabs to documents using anchor strings (For example, 'DevSignHere'). But if we add another document later for the same recipient with the same anchor strings, DocuSign doesn't add those tabs on those anchor strings.
How can I tell DocuSign to 'look again' for anchor strings?
Once you have added a new document then you need to call below API for the recipient to create new Tabs on the new document:
POST /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs
DS Docs
Example:
POST /restapi/v2/accounts/<accountId>/envelopes/<envelopeId>/recipients/1/tabs
{
"dateSignedTabs": [
{
"anchorString": "\\D1\\",
"recipientId": "1",
"tabLabel": "internal_date"
}
],
"signHereTabs": [
{
"anchorString": "\\S1\\",
"recipientId": "1",
"tabLabel": "internal_sign"
}
],
"textTabs": [
{
"anchorString": "\\T1\\",
"recipientId": "1",
"tabLabel": "internal_contact"
}
]
}
If the new document's fields (Tabs) are managed by a template, then you can use Composite Templates to have the document "processed" by the right template. Ask this as a new question if you want to investigate this route.
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",
}
]
}
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.