I am trying to update the textTabs for a particular envelope recipient of a draft Docusign envelope.
For this I am using the PUT EnvelopeRecipientTabs endpoint. But I am always getting this error.
I intend to update the value of an existing text tab of the particular recipient.
"textTabs": [
{
"requireAll": "false",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"recipientId": "3",
"tabId": "00000000-0000-0000-0000-000000000000",
"errorDetails": {
"errorCode": "INVALID_TAB_OPERATION",
"message": "The Tab specified is not valid for the requested operation. Tab not found in envelope."
}
}
}
Are you specifying a tabId? You need to. Before your EnvelopeRecipientTabs::update call, call EnvelopeRecipientTabs::list to learn the tabId.
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 know that there is no authentication performed by Docusign when using embedded signers. In the RecipientViewReuest it allows for an authentication_method. So far I have found that 'none' and 'email' work fine. I assumed that this was a free form text field that allowed me to say something like 'Checked their IDs' But any I've used so far (besides none and email) cause an error, so I assume there a limited list of acceptable answers. Anyone know what they are?
You can enable the following recipient authentication types on your envelope:
Access Code
Phone Authentication
SMS
Knowledge-Base Authentication(KBA)
ID Verification (IDV)
In your case (for embedded signing) you have two separate API requests to make: The only change will come in your POST /envelopes call.
Ex. Let's say I wanted to add an access code to a particular recipient. Easy as adding the accessCode property when you create your envelope.
{
"documents": [{
"documentBase64": "JVBERi0xLjMNJeLjz...lRU9GDQo=",
"documentId": "1",
"fileExtension": "pdf",
"name": "Lorem"
}],
"emailBlurb": "Sample text for email body",
"emailSubject": "Please Sign",
"envelopeIdStamping": "true",
"recipients": {
"signers": [{
"name": "{SIGNER_NAME}",
"email": "{SIGNER_EMAIL}",
"roleName": "",
"note": "",
"routingOrder": 1,
"accessCode": "{ACCESS_CODE}"
"status": "created",
"tabs": {
"signHereTabs": [{
"documentId": "1",
"name": "SignHereTab",
"pageNumber": "1",
"recipientId": "1",
"tabLabel": "SignHereTab",
"xPosition": "75",
"yPosition": "572"
}]
}
}]
},
"status": "Sent"
}
Here is a full guide on this topic.
Matthew has provided the list of additional authentication that DocuSign can do for you if you wish.
Here is the list of authentications that you can list as having performed before calling the EnvelopeViews:createRecipient method.
They're listed on that page in the description for the recipientViewRequest.authenticationMethod attribute. Use the value that best describes the authentication that your application did.
Biometric
Email
HTTPBasicAuth
Kerberos
KnowledgeBasedAuth
None
PaperDocuments
Password
RSASecureID
SingleSignOn_CASiteminder
SingleSignOn_InfoCard
SingleSignOn_MicrosoftActiveDirectory
SingleSignOn_Other
SingleSignOn_Passport
SingleSignOn_SAML
Smartcard
SSLMutualAuth
X509Certificate
I have a Word document that serves as the Document template. It only has an outline on it. I then added text fields to the template.
for example, the template JSON, it looks like this:
"recipients":
{ ...
"signers": [
{ ...
"tabs":
{
"listTabs": [
{
"documentId": "1",
"pageNumber": "1",
"recipientId": "55177519",
"tabType": "list",
"tabLabel": "##parentf2e8b853-3ef1-4872-af19-4f1e3c60a3a7##recipient",
"listItems": [
{
"text": "Dealer",
"value": "Dealer"
},
{
"text": "Customer",
"value": "Customer"
}
],
"required": "true",
"shared": "true",
"value": ""
}
],
"textTabs": [
{
"documentId": "1",
"height": "19",
"pageNumber": "1",
"recipientId": "55177519",
"tabId": "55ab5a10-54d6-4ca0-a66b-7c637c8ad61a",
...
"tabLabel": "DealerPhone",
...
},
My questions are:
How can I get all of the text fields to display the data, no matter who the recipient is- for example, the DealerPhone above? Under "Collaboration", I have set the fields set to "Recipients can Collaborate".
Once the first user selects the user from the drop-down list (the listTab below), I do not want subsequent users to go in and change that selection, but I do need the users to see who the previous / first user selected in that drop-down list.
I can share JSON files of both the template and what I'm sending to create the envelope. The template displays, but the text data is blank.
Sample JSON request body:
{
"email": "...email....",
"name": "Test Dealer",
"roleName": "Dealer",
"tabs": {
"textTabs": [
{
"tabLabel": "DealerPhone",
"value": "1-800-111-2222"
},
{
"tabLabel": "DealerContact",
"value": "Billy Dealer"
}]
}
}],
"emailSubject": "DocuSign API - TEST!!!",
"templateId": "{{templateId}}",
"status": "sent"
}
There's an account-level setting that's relevant here, available from Go to Admin > Sending Settings > When an envelope is sent, write the initial value of the field for all recipients. With that enabled, all pre-populated data will be visible to all recipients. With that disabled, data only gets 'burned in' to the PDF when the assigned recipient completes their role.
If you do not want later recipients to be able to change the value of the dropdown, you will want to disable Collaboration on it. Later signers will be able to see that selection regardless of if Collaboration is enabled or not.
Finally, you'll want to avoid using Conditional Logic on fields that should always appear. Setting a tag to be a conditional child means that it will only appear if circumstances are met.
If recipients sign sequentially (increasing routing order) then every subsequent recipient can see the tabs that prior recipients have filled and they cannot modify them. If you have all tabs assigned to your first recipient, all the other recipients will see them but they'll be read-only for them.
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.
We are using embedded Signing feature. We are using templates for generating envelopes for embedded signing. We have a requirement for downloading pdf (before signing). This pdf should contain pre-populated data in envelope. We have tried to download pdf by using rest API as below, but it is giving blank (without prepopulated value - as in template) pdf. Is there any way to achieve the same?
https://demo.docusign.net/restapi/v2/accounts/{our account id}/envelopes/{envolopID}/documents/{documentId}
The way that DocuSign works is that when you layer data fields and other DocuSign tabs onto your documents they are not part of the document until it is signed by the recipients who are to take actions on those tabs. One of the reasons is because someone might change the initial data to something else when it is their turn to sign (if they have permissions to) so when the document is still pending the pre-populated values are not included in the download.
You can, however, still retrieve the values of your fields while the envelope is still pending. Since tabs are always specific to recipients you need to download tab information for whichever recipients they are configured for.
To download the tabs for this recipient including the initial pre-populated values you would make the following api call:
URL:
/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs
Formats:
XML, JSON
HTTP Method:
GET
HTTP Body:
(empty)
If the envelope in question had one data field (textTab) which has the value "test data", then the response would look like:
"textTabs": [
{
"height": 11,
"validationPattern": "",
"validationMessage": "",
"shared": "false",
"requireInitialOnSharedChange": "false",
"name": "Text",
"value": "test data",
"width": 138,
"required": "true",
"locked": "false",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"tabLabel": "Data Field 3",
"bold": "false",
"italic": "false",
"underline": "false",
"documentId": "1",
"recipientId": "58576405-2f0b-45a4-998b-1cb81b769d22",
"pageNumber": "1",
"xPosition": "105",
"yPosition": "499",
"tabId": "7e1441bc-700e-43d4-b968-b7fa36887ee2"
}
]