I'm attempting to add a recipient to a draft envelope and althought the recipient does get added I receive an error message related to the notification. Could someone explain the USER_LACKS_RECIPIENTEMAILNOTIFICATION_PERMISSION error is exactly?
POST /restapi/v2/accounts/123456/envelopes/3a20bef6-0d88-431a-aaf1-e27baa9b59a6/recipients HTTP/1.1
{
"carbonCopies": [
{
"email": "my#emailaddress.com",
"name": "Mike",
"accessCode": "xyz",
"addAccessCodeToEmail": true,
"emailNotification": {
"emailBody": "Custom email message different than the envelope body",
"emailSubject": "Custom email subject",
"supportedLanguage": "en"
},
"inheritEmailNotificationChange": false,
"note": "Sample note",
"recipientId": "1",
"routingOrder": "1"
}
]
}
And here is the response that I receive back:
{
"signers": [],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [
{
"name": "Mike",
"email": "my#emailaddress.com",
"recipientId": "1",
"accessCode": "xyz",
"requireIdLookup": "false",
"routingOrder": "1",
"note": "Sample note",
"status": "error",
"emailNotification": {
"emailSubject": "Custom email subject",
"emailBody": "Custom email message different than the envelope body",
"supportedLanguage": "en"
},
"errorDetails": {
"errorCode": "USER_LACKS_RECIPIENTEMAILNOTIFICATION_PERMISSION",
"message": "Account or user does not have permission to set recipient email notifications."
}
}
],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "1"
}
The only permission setting that I can see might pertain to this is the following, but I can not change it's value.
The answer to get around this issue is to not supply the ""supportedLanguage" property for the recipient. This is a feature that will need to be turned on for your sending user in order to use it.
Check the "Reminders & Expirations" section to make sure you don't have the "Do NOT allow users to override these settings" setting checked?
Related
I'm trying to add anchor tagging when I create a new envelope, but the tab to sign doesn't appear.
I've followed these steps:
Created a template
POST {{baseUrl}}/v2.1/accounts/{{accountId}}/templates
{"name": "Template 1",
"emailBlurb": "Blurb Test",
"emailSubject": "Subject Test",
"documents": [{
"documentId": "1",
"name": "Document1",
"fileExtension": "pdf",
"order": "1",
"documentBase64":"base64codehere" }]
}
Created an envelope
POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes
{"status": "created", "templateId": "{{templateId}}" }
Add recipient to the envelope
POST {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/recipients
{
"signers": [
{
"userName" : "Sender 1",
"email": "sender1email#gmail.com",
"name": "Sender 1",
"clientUserId": "SenderOne" ,
"recipientId": "1",
"roleName" : "SenderMember",
"routingOrder": "1",
"tabs": {
"signHereTabs": [
{
"anchorString": "\\sn1\\",
"anchorXOffset": "20",
"anchorYOffset": "10",
"anchorUnits": "pixels"
}
]
}
},
{
"userName" : "Sender2",
"email": "sender2email#gmail.com",
"name": "Sender2",
"clientUserId": "Sender2C" ,
"recipientId": "2",
"roleName" : "SenderMember2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"anchorString": "\\sn1\\",
"anchorXOffset": "20",
"anchorYOffset": "10",
"anchorUnits": "pixels"
}
]}}
]
}
Got recipients from envelope
GET {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}/recipients
{
"signers": [
{
"creationReason": "sender",
"isBulkRecipient": "false",
"requireUploadSignature": "false",
"name": "Sender 1",
"firstName": "",
"lastName": "",
"email": "sender1email#gmail.com",
"recipientId": "1",
"recipientIdGuid": "ed850c16-be9b-45d1-b0a2-b06f9d043a33",
"requireIdLookup": "false",
"userId": "66f3947d-eea4-450a-9f3a-6145607dba20",
"clientUserId": "SenderOne",
"routingOrder": "1",
"roleName": "SenderMember",
"status": "created",
"completedCount": "0",
"deliveryMethod": "email",
"recipientType": "signer"
},
{
"creationReason": "sender",
"isBulkRecipient": "false",
"requireUploadSignature": "false",
"name": "Sender2",
"firstName": "",
"lastName": "",
"email": "sender2email#gmail.com",
"recipientId": "2",
"recipientIdGuid": "88f5e6e2-9e95-4d94-9501-0ebdfeece93b",
"requireIdLookup": "false",
"userId": "4843e0fa-a69c-43ce-9638-e9d1c023ad27",
"clientUserId": "Sender2C",
"routingOrder": "2",
"roleName": "SenderMember2",
"status": "created",
"completedCount": "0",
"deliveryMethod": "email",
"recipientType": "signer"
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [],
"certifiedDeliveries": [],
"inPersonSigners": [],
"seals": [],
"witnesses": [],
"notaries": [],
"recipientCount": "2"
}
5 - Sent envelope
GET {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes/{{envelopeId}}
{
"status": "sent"
}
When I check the document, I do not see any sign tab:
DocuSign Document with the tags
Am I doing something wrong?
I suggest you follow our two how-to articles about this:
How to create a template
How to request a signature using a
template
Note that by putting the recipients as "placeholders" on the template, you can still define them differently for each envelope using the templateRoles object as long as you match the roleName. You will then get all the tabs that you defined to show on the envelope created from that templates.
Auto-place works fine with sign tabs. So the issue is to figure out what's happening with your app.
First off, most important please do not create an envelope by using multiple API calls to build up the envelope unless there's a real good reason why your application requires that pattern.
In general, building up an envelope via multiple API calls is not an efficient use of the API and is not allowed per DocuSign's API Usage Guidelines.
Instead, you can use one API call to create all aspects of the envelope and send it.
Easiest example to see how to use anchor tags with signHere tabs is the API Request Builder live examples. It enables you to try out the API and it then creates the SDK calls for you in various languages.
My guess from looking at your code is that the anchor strings are not matching with the document's text.
Using the following POST request and body to send an envelope (source https://developers.docusign.com/docs/esign-rest-api/how-to/request-signature-template-remote)
https://demo.docusign.net/restapi/v2.1/accounts/4f4xxxx-xxxxxx-xxxxxx/envelopes
{
"templateId": "dbexxxx-xxxxx-xxxxx",
"templateRoles": [
{
"email": "test#gmail.com",
"name": "John Doe",
"roleName": "signer1",
"tabs": {
"textTabs": [
{
"tabLabel": "cname",
"value": "name"
}
]
}
}
],
"status": "sent"
}
Is there a way to specify the email message, email subject and/or email language? I tried adding "emailSubject": "Please sign ..." next to "email" but cannot seem to make it work. It is a requirement that I need to manually make this post request so I cannot use the SDK.
Where you placing the "emailSubject" field exactly in your JSON?
You can specify the the email message and subject by specifying the following fields at the root level (where you "status" is defined):
{
"emailBlurb": "げりト画首ロ百照ょリっ毎現イタヱア掲全らいに",
"emailSubject": "Subject of agreement",
"templateId": "867a37*****",
"templateRoles": [
{
"email": "email#domain.com",
"name": "name_of_person",
"roleName": "Seller"
}
],
"status": "sent"
}
I have integrated DocuSign APIs with my application. DocuSign provides feature to assign signing responsibility to someone else. When I try to get the status of all the recipients I am unable to identify which signer delegated his responsibility to which signer.
{
"witnesses": [],
"seals": [],
"intermediaries": [],
"currentRoutingOrder": "1",
"carbonCopies": [{
"requireIdLookup": "false",
"recipientId": "1",
"status": "completed",
"email": "charles#gmail.com",
"recipientIdGuid": "15e02ae9-a4cb-4562-a05f-381d9d555894",
"userId": "0e6e3f29-6f69-4b48-92a1-be7443b0ac58",
"name": "Charles Kom",
"routingOrder": "1"
}],
"agents": [],
"recipientCount": "2",
"signers": [{
"requireIdLookup": "false",
"recipientId": "155500",
"creationReason": "sender",
"status": "sent",
"email": "anna#gmail.com",
"recipientIdGuid": "405ccc6e-b6b4-4d7a-b21a-cfab853a8499",
"userId": "521911fd-3215-4a83-93f3-7a62991ca64d",
"name": "Anna",
"routingOrder": "1",
"identityVerification": {},
"note": "sdfsae",
"isBulkRecipient": "false"
}],
"editors": [],
"inPersonSigners": [],
"certifiedDeliveries": []
}
This is the response I receive from API. Here there is no mean to find which signer delegated responsibility to whom if I have more than one signers and more than one have delegated.
Is there any other API to find out this thing?
One possible solution I thought is DocuSign also has feature of View Envelope History. But I couldn't found any REST API for that.
GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/audit_events is the API call to get the envelope audit history. On check the response, you will the Action as Reassign and Message also will have Original Signer and new Signer's name and email address.
{
"name": "Action",
"value": "Reassign"
},
{
"name": "Message",
"value": "John Smith reassigned the envelope to Daisy Duck [daisyduck+delegate#gmail.com] routing order 1"
}
DS Docs has more details about this API.
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'm interested in getting roles from templates to populate them correctly and keep that up to date automatically.
Is it somehow possible to get that using REST API?
There's the "Get Account Template by ID - v2/accounts/:accountId/templates/:templateId" request but it seems to return little useful info regarding roles or recipients.
Using the REST API, you can get recipient Role Names for a Template by simply executing a "GET Envelope Recipients" request, where you specify the Template Id in place of the Envelope Id. For example:
GET https://demo.docusign.net/restapi/v2/accounts/{accountId}/envelopes/{templateId}/recipients?include_tabs=false&include_extended=true
The response to this request will contain an array of recipient objects for each recipient type (i.e.: signers, agents, editors, intermediaries, carbonCopies, certifiedDeliveries, inPersonSigners); each recipient object will contain the property roleName. Here's an example response for a template that contains 3 recipients -- 2 signers and one CC recipient:
{
"signers": [
{
"signInEachLocation": "false",
"name": "",
"email": "",
"recipientId": "5741ec70-b056-44eb-b462-eceee88ddf77",
"requireSignerCertificate": "false",
"requireIdLookup": "false",
"routingOrder": "1",
"roleName": "Signer 1",
"status": "created",
"templateLocked": "false",
"templateRequired": "false"
},
{
"signInEachLocation": "false",
"name": "",
"email": "",
"recipientId": "c64d4567-2efd-422d-9b0a-a5427aa2512d",
"requireSignerCertificate": "false",
"requireIdLookup": "false",
"routingOrder": "2",
"roleName": "Signer 2",
"status": "created",
"templateLocked": "false",
"templateRequired": "false"
}
],
"agents": [],
"editors": [],
"intermediaries": [],
"carbonCopies": [
{
"name": "Legal Team",
"email": "email3#outlook.com",
"recipientId": "a63e3714-adc2-4e05-b2c5-b3c3bbf50aa2",
"requireIdLookup": "false",
"routingOrder": "3",
"roleName": "Legal Team",
"status": "created",
"templateLocked": "true",
"templateRequired": "true"
}
],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "3"
}