My application lets a user connect their account via OAuth, then can send an envelope to a user based on a template. However, the send fails with a 400 response.
I am making two requests - one POST to create an envelope from a template (which receives a 201 response), and one PUT against the new envelope to send it with some tab data populated. However, the send call fails with the following 400 response:
{
"errorCode": "ENVELOPE_HAS_DUPLICATE_RECIPIENTS",
"message": "The specified envelope has duplicate recipients."
}
The first call to create the envelope contains this body:
{
"eventNotification": {
"envelopeEvents": [
{
"envelopeEventStatusCode": "Completed"
}
],
"includeSenderAccountAsCustomField": "true",
"includeTimeZone": "true",
"loggingEnabled": "true",
"requireAcknowledgment": "true",
"url": "https://mywebsite.com/webhook/receive/docusign"
},
"templateId": "a65ae540-16eb-4078-aab9-2dff5c2eda25",
"templateRoles": [
{
"email": "me#example.org",
"name": "My Name",
"roleName": "Employee"
}
]
}
And the second (failing) call contains this body:
{
"recipients": {
"signers": [
{
"email": "me#example.org",
"name": "My Name",
"recipientId": "92174826",
"tabs": {
"fullnameTabs": [
{
"documentId": "1",
"pageNumber": "1",
"tabId": "eb0c7a2d-5912-4cf1-8e2b-fd17fd7fb63c",
"value": "My Name"
},
{
"documentId": "1",
"pageNumber": "3",
"tabId": "92fb908c-6f84-472a-aa9d-baaa29758c12",
"value": "My Name"
}
]
}
}
]
},
"status": "sent"
}
Some values (names, emails etc) have been changed for privacy. The template contains a single recipient - Employee.
What am I doing wrong?
add a "routingOrder" property with a different number.
You cannot have two recipients with the same email/name and the same routing order.
Related
How do I create a recipient with both email and SMS?
I've been unable to find example JSON that addresses this issue. The documentation on Docusign's website shows either email or SMS, not both together (that I can find, anyway). I found a note somewhere that suggested it's possible, but I can't find it again.
If your account has SMS Delivery enabled, you can make an API Request in the following format to send an envelope with Email + SMS Delivery
{
"documents": [
{
"documentBase64": "Base 64 here",
"documentId": 1,
"fileExtension": "txt",
"name": "Filename"
}
],
"emailSubject": "Blurb",
"recipients": {
"signers": [
{
"email": "Recipient Email Here",
"name": "DocuSigner",
"recipientId": "1",
"tabs": {
"signHereTabs": [
{
"xPosition": "10",
"yPosition": "10"
}
]
},
"additionalNotifications": [
{
"secondaryDeliveryMethod": "SMS",
"phoneNumber": {
"countryCode": "Code",
"number": "Phone number"
}
}
]
}
]
},
"status": "sent"
}
Many questions address portions of my request, but I cannot seem to make a complete solution work. I have created a template on my site (it has various text fields, initial fields, and signature block). Single recipient, using anchor tags for the fields. When I take a .docx file, create an envelope via the api, I want to apply the template previously mentioned, and then prefill 4 text fields on the document/template.
Anchor tags are not placing the fields appropriately.
Any advise/suggestions?
Working request call is:
{
"documents":
[
{
"documentBase64":"<BASE64STREAM>",
"documentId":"3",
"fileExtension":"docx",
"name":"10001000_20170803_FILE"
}
],
"emailSubject": "TEST - Group Audit - 10001000",
"templateId": "TEMPLATE_ID",
"templateRoles" :
[
{
"email": "JDOE#email.com",
"name": "JOHN DOE",
"roleName": "signer1",
"tabs":
{
"textTabs":
[
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "groupname",
"value": "TEST GROUP ONE"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "groupnumber",
"value": "10001000"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "txt",
"value": "my#email.com"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "fein",
"value": "870142380"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "physicaladdress",
"value": "1 STREET WAY, , MY CITY, CA, 98001"
}
]
}
}
],
"status":"sent"
}
Based on the information you've provided, I understand your scenario to be as follows:
You've created a template via the DocuSign UI; that template contains a 'placeholder' document (which you will replace at run-time via your Create/Send Envlope API call) and defines the recipient(s) and tabs for that document.
When you create/send the envelope via API, you want to specify the document as part of the API request (i.e., to be used instead of the 'placeholder' document that the DocuSign template contains) and also auto-populate some of the tabs that the template defines.
If that's an accurate description of what you're trying to achieve, then you need to use Composite Templates in the API request structure. Here's an example of a Create/Send Envelope JSON request that uses composite templates (and contains data based upon the information you provided in your question):
{
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "TEMPLATE_ID"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "JOHN DOE",
"email": "JDOE#email.com",
"roleName": "signer1",
"tabs":
{
"textTabs":[
{
"tabLabel" : "groupname",
"value" : "TEST GROUP ONE"
},
{
"tabLabel" : "groupnumber",
"value" : "10001000"
},
{
"tabLabel" : "txt",
"value" : "my#email.com"
},
{
"tabLabel" : "fein",
"value" : "870142380"
},
{
"tabLabel" : "physicaladdress",
"value" : "1 STREET WAY, , MY CITY, CA, 98001"
}
]
}
}
]
}
}
],
"document": {
"documentId": "3",
"name": "10001000_20170803_FILE.docx",
"fileExtension": "docx",
"documentBase64": "BASE64STREAM"
}
}
],
"status": "sent",
"emailSubject": "TEST - Group Audit - 10001000"
}
I have been experimenting with the DocuSign eSign C# library, and everything has been working as expected for single template envelopes. I now need to use 2 different templates within a single envelope and have run into some issues.
I have 2 templates that I wish to combine. Everything works exactly as expected when I create a composite template, add the necessary recipients, and send the notification. This sends the combined templates to both recipients in parallel.
As soon as I add a RoutingOrder of 1/2 to the recipients, the first recipient gets prompted to sign as expected, and then once signed it is passed on to the second recipient. This is where the problem lies... the second recipient doesn't have any tabs to fill in and/or any place to sign.
If I switch the RoutingOrder of the recipients, I get the same behavior, so it is definitely related to a person being the second recipient.
Any thoughts on what I can do to fix this are greatly appreciated! The JSON generated by the DocuSign eSign API can be found below:
{
"eventNotification": {
"url": "<my_webhook_callback_url>",
"loggingEnabled": "true",
"requireAcknowledgment": "true",
"envelopeEvents": [
{ "envelopeEventStatusCode": "sent" },
{ "envelopeEventStatusCode": "delivered" },
{ "envelopeEventStatusCode": "completed" },
{ "envelopeEventStatusCode": "declined" },
{ "envelopeEventStatusCode": "voided" }
],
"recipientEvents": [
{ "recipientEventStatusCode": "Sent" },
{ "recipientEventStatusCode": "Delivered" },
{ "recipientEventStatusCode": "Completed" },
{ "recipientEventStatusCode": "Declined" },
{ "recipientEventStatusCode": "AuthenticationFailed" },
{ "recipientEventStatusCode": "AutoResponded" }
],
"useSoapInterface": "false",
"includeCertificateWithSoap": "false",
"signMessageWithX509Cert": "false",
"includeDocuments": "true",
"includeEnvelopeVoidReason": "true",
"includeTimeZone": "true",
"includeSenderAccountAsCustomField": "true",
"includeDocumentFields": "true",
"includeCertificateOfCompletion": "true"
},
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "1b5230a2-15da-4502-8ea4-9a7a28ae02aa"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"name": "<customer_signer_name>",
"email": "<customer_signer_name>",
"recipientId": "1",
"routingOrder": "1",
"roleName": "Customer"
},
{
"name": "<internal_signer_name>",
"email": "<internal_signer_email>",
"recipientId": "2",
"routingOrder": "2",
"roleName": "InternalSigner"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "ae08ac4b-2d92-43cc-9c18-5eaa0a6cc8c7"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"name": "<customer_signer_name>",
"email": "<customer_signer_name>",
"recipientId": "1",
"routingOrder": "1",
"roleName": "Customer"
},
{
"name": "<internal_signer_name>",
"email": "<internal_signer_email>",
"recipientId": "2",
"routingOrder": "2",
"roleName": "InternalSigner"
}
]
}
}
]
}
],
"status": "sent",
"emailSubject": "Test Email Subject"
}
Your server templates have both the recipients at routing order 1. Since the inlineTemplates specify the recipient at routing Order 2, the tabs in the server template will not be associated with the recipient at routing order 2.
Recipient matching is based on Recipient Role and Routing Order. If there are matches, the recipient information is merged together. A final pass is done on all CompositeTemplates, after all template overlays have been applied, to collapse recipients with the same email, username and routing order. This prevents having the same recipients at the same routing order.
You will have to either update the routing order of the recipient on your server template or specify tabs in the inline template.
I have an embedded signing application where users going through a web interview have to sign certain documents at the end. The documents are generic templates, currently defined with the user name and email address left blank. I am providing the user name, email address and a clientUserId in the envelope creation, matching the role that is defined in the template. But I keep getting the error UNKNOWN_ENVELOPE_RECIPIENT - The recipient you have identified is not a valid recipient of the specified envelope. What constitutes a "valid recipient" of a generic template? Am I supposed put something in the user and email fields of the template? I'm confused.
In answer to Larry K below, that appears to be exactly what I have done. Here's the JSON for the create envelope request that results in the error:
{
"accountId":"1234567",
"emailSubject":"Certification Documents",
"status":"sent",
"compositeTemplates":[
{
"serverTemplates":[
{
"sequence":"1",
"templateId":"5ed3d600-5a57-4fee-931f-53233858dc65"
}
],
"inlineTemplates":[
{
"sequence":"1",
"recipients":{
"signers":[
{
"name":"John Doe",
"roleName":"Applicant",
"recipientId":"1",
"clientUserId":"62",
"email":"jd#mydomain.com",
"tabs":{
"textTabs":[
{
"tabLabel":"EmplName",
"value":"John Doe"
},{
"tabLabel":"SSN",
"value":"123456789"
},{
"tabLabel":"DoB",
"value":"08\/26\/1991"
}
]
}
}
]
}
}
]
}
]
}
Here is the Get Recipients response:
{
"signers": [
{
"isBulkRecipient": "false",
"name": "",
"email": "",
"recipientId": "63543029",
"recipientIdGuid": "29a731f6-2f82-490f-9589-f551727414d9",
"requireIdLookup": "false",
"smsAuthentication": {},
"routingOrder": "1",
"note": "",
"roleName": "Applicant",
"status": "created",
"declinedReason": "",
"deliveryMethod": "email",
"templateLocked": "false",
"templateRequired": "false"
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [
{
"name": "Real Person",
"email": "rp#mydomain.com",
"recipientId": "83856197",
"recipientIdGuid":
"0f80a5ab-2050-472a-b072-7a18794a4726",
"requireIdLookup": "false",
"smsAuthentication": {},
"routingOrder": "1",
"note": "",
"roleName": "Mancon",
"status": "created",
"declinedReason": ""
}
],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "2"
}
I've got it. Too many iterations of messing with code, mixing live code with debug stuff. It looked like the error was coming from the envelope creation because I had stepped on a debug message. But in fact the code was going through to the signing view request, which actually was generating the error. And there, as you might guess, was a debug clientUserId, which did not match the envelope. I hate it! Thanks for the coaching. It eventually led me to the real problem.
To troubleshoot, I'd suggest executing a Get Template Recipients request for the Template you're using (GET /v2/accounts/{accountId}/templates/{templateId}/recipients), then compare the contents of that response with the recipients portion of your Create Envelope From Template request that's resulting in the error UNKNOWN_ENVELOPE_RECIPIENT. If you can't spot a difference, feel free to update your post (question above) with the trace of your original Create Envelope request as well as the response from Get Template Recipients (removing any sensitive info, of course), and perhaps someone here can spot the issue.
Another answer from a second DocuSign consultant:
He suggests that perhaps the reason you received the error was that you didn't use the exact same triplet of {recipient/signer name, email, client id} in both your call to Envelopes: create and to EnvelopeViews: createRecipient
The following should work:
Call to Envelopes: create:
{
"emailSubject":"My subject",
"emailBlurb":"My blurb",
"templateId":"My template id",
"templateRoles":[
{
"clientUserId":"123456789",
"roleName":"My role",
"name":"Name",
"email":"email"
}
],
"status":"sent"
}
Call to EnvelopeViews: createRecipient:
{
"authenticationMethod": "password",
"email": "email",
"returnUrl": "https://www.docusign.com",
"userName": "Name",
"clientUserId": "123456789"
}
A solution from one of our DocuSign consultants is below. He recommends compositing the recipient information with the template. Here's the json for the Envelopes: create call:
{
"emailSubject": "Create Envelope with embedded recipient",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "{Template ID}"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"clientUserId": "Unique Identifier",
"email": "signer1#example.com",
"name": "Signer One",
"recipientId": "1",
"roleName": "Customer"
}
]
}
}
]
}
]}
I want to create a composite envelope and then do an embedded signing. The issue is that the envelope is created but the call to get the url fails.
First I create the composite envelope:
https://demo.docusign.net/restapi/v2/accounts/ACCOUNT/envelopes
{
"emailSubject": "DocuSign API - Composite Templates",
"emailBlurb": "Composite Templates Sample 1",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "1AA7BA0B-9079-4F8C-915B-739576297D62"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "email#email.com",
"name": "Signer Name",
"recipientId": "1",
"roleName": "Account Holder"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "2",
"templateId": "77343ECC-391F-46A1-BFC3-92A3CD8C93E3"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "email#email.com",
"name": "Signer Name",
"recipientId": "1",
"roleName": "Account Holder",
"tabs": {
"textTabs": [
{
"tabLabel": "AccountFirstName",
"value": "Client"
},
{
"tabLabel": "AccountLastName",
"value": "Name"
},
{
"tabLabel": "Email1",
"value": "someEmail#email.com"
}
]
}
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "3",
"templateId": "ADADDD87-E831-4EF3-A160-BBE73F449C8E"
}
],
"inlineTemplates": [
{
"sequence": "3",
"recipients": {
"signers": [
{
"email": "email#email.com",
"name": "Signer Name",
"recipientId": "1",
"roleName": "Account Holder"
}
]
}
}
]
}
]
}
The response is:
{
"envelopeId": "99f4c73d-6420-4e3b-88eb-2447139a2616",
"uri": "/envelopes/99f4c73d-6420-4e3b-88eb-2447139a2616",
"statusDateTime": "2014-08-14T21:09:09.0430000Z",
"status": "sent" }
Next I try to get the recipient view
https://demo.docusign.net/restapi/v2/accounts/ACCOUNT/envelopes/99f4c73d-6420-4e3b-88eb-2447139a2616/views/recipient
{
"authenticationMethod": "email",
"email": "email#email.com",
"returnUrl": "www.someUrl.com",
"userName": "Signer Name"
}
And I get this error:
{
"errorCode": "UNKNOWN_ENVELOPE_RECIPIENT",
"message": "The recipient you have identified is not a valid recipient of the specified envelope. Envelope recipient could not be determined. 'clientUserId', 'email', or 'userName' in request and envelope may not match."
}
The email and the names match up so I do not understand why I am unable to get the url. I should point out that this all works if I use the same name and email that is on the DocuSign account, but this needs to work for an external recipient.
To designate a recipient as an embedded/captive recipient when creating an Envelope, such that you'll subsequently be able to submit a "Get Recipient View" request to retrieve a URL that can be used to initiate the recipient's signing session, your "Create Envelope" request must specify the clientUserId property for the recipient. This property should appear as a peer to the other recipient properties (i.e.: email, name, etc.) -- like this:
"signers": [
{
"email": "email#email.com",
"name": "Signer Name",
"recipientId": "1",
"roleName": "Account Holder",
"clientUserId": "12345"
}
]
Then, when you submit the "Get Recipient View" request, you'll need to specify the same value for clientUserId there:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/ENVELOPE_ID/views/recipient
{
"authenticationMethod": "Email",
"email": "email#email.com",
"returnUrl": "www.someUrl.com",
"userName": "Signer Name",
"clientUserId": "12345"
}
The value of clientUserId can be anything you wish, but max length is 100 characters. See the DocuSign REST API Guide for more details about embedded signing.