I would like to create envelopes for embedded/captive recipients using SOAP based API calls and generate a token with which a recipient can sign the envelope right after it gets created.
I have followed your documentation but am not able to create token(s) for the embedded signer(s). I am able to create an envelope but while creating the tokens, I get an error
"Invalid Signature Credentials".
According to your documentation, while creating an envelope with captive recipient,I need to pass in clientuserid for the recipient. I need to use the same clientuserid for the same recipient each time.
It looks like, I might have created an envelope with a captive recipient before but I am not using the right combination..Recipient name, email address and clientuserid every time I am creating an envelope with captive recipient(s).
1) Is there a way to reassign the clientuserid to the recipient?
2) Is there a way to retrieve the clientuserid for the recipient?
3) From the DocuSign account, how do we check if an envelope has been created with a captive recipient(s)?
4) Do we have to turn any setting on from our DocuSign account to create envelopes with captive recipients?
1) You might be able to use the Recipient Correction call to update the clientUserId for a given recipient, but if that does not work you can always remove the recipient from the envelope, then re-add as an Embedded recipient.
2) To retrieve the clientUserId value and other information for your recipients you need to make the following API call:
Get Envelope Recipient Status
URI:
/accounts/{accountId}/envelopes/{envelopeId}/recipients
Method:
GET
Sample Response:
{
"recipientCount":"String content",
"signers":[{
"deliveredDateTime": "String content",
"recipientAuthenticationStatus":{
"(authentication status result)":
"eventTimestamp":"String content"
"status":"String content"
}
},
"recipientId": "String content",
"clientUserId": "String content",
"requireIdLookup": "String content",
"roleName":"String content",
"routingOrder": "String content",
"signedDateTime": "String content",
"status": "String content",
"email": "String content",
"name": "String content" }]
}]
}
3) I'm not sure if you can check through the DocuSign Console, the API call described above will indicate if a given recipient is captive or not. If the have a clientUserId value defined, they are embedded - otherwise they are a remote signer.
4) Yes, this is a feature that you're API integration would need to include in its account plan. Talk to your DocuSign account manager for more information.
Related
I'm trying to figure out how to use the access code for a signer. In the api there is the accesscode field and a addaccesscodetoemail field. If I want the signer to see the accesscode in the email, do I just set that value to the accesscode and then set addaccesscodetoemail = true?
Yes, If you want the signer to see the accesscode in the email, then you just set that value to the accesscode and then set addaccesscodetoemail = true and signer will see the accesscode in the email itself. But it is not a good practice as it defeats the purpose of using the accesscode. Ideally, you should set accesscode via API and then communicate accesscode to the signer via another channel (not by sending the accesscode in an envelope notification email).
DocuSign's Access code authentication is similar to sms authentication except that for access code it's up to the sender to determine how to actually get the code over to the recipient.
They can send their own SMS outside of DocuSign platform with the code, they can send their own custom email, call the person, etc - but the bottom line is that DocuSign will not include the code in the system generated email.
To configure an access code for a recipient you have to set it on the specific type of recipient, in this case signer for example:
"recipients":
{
"signers": [
{
"email": "test_1#email.com",
"name": "Name 1",
"accessCode": "1234",
...
Once a user signs a document attached to an envelope, is there anyway that developer can download that document using Rest API end-point? And before downloading it, is there any way to tell whether the document is signed or not?
Part I: Determine whether a particular signer OR whether all recipients have completed/submitted an Envelope
To check whether a particular Signer (recipient) has completed signing an Envelope, you can use the List Envelope Recipients request:
GET /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients
As shown here, the signers property within the JSON response is the array of signers for the Envelope, and the status property within each signer object indicates that particular recipient's status. A status of completed for a signer indicates that the recipient has signed/completed/submitted the Envelope.
{
...
"signers": [
{
"deliveredDateTime": "2016-10-05T21:18:12.3330000Z",
"email": "jallard#example.com",
"isBulkRecipient": "false",
"name": "Jennie Allard",
"recipientId": "1",
"recipientIdGuid": "4575d5e9-7654-467b-b2f5-6c59ca7c43f8",
"requireIdLookup": "false",
"routingOrder": "1",
"signedDateTime": "2016-10-05T21:18:41.6930000Z",
"status": "completed",
"userId": "ca45284a-a94e-4ee2-90af-76035bd795b2"
}
]
}
Alternatively, to check whether ALL recipients of an Envelope have completed/submitted the Envelope, you can use the Get Envelope request:
GET /v2/accounts/{accountId}/envelopes/{envelopeId}
As shown here, the response will be an Envelope object and the status property within that object indicates the overall status of the Envelope. A status of completed indicates that all recipients have completed/submitted the Envelope.
Part II: Download completed document(s)
For endpoints related to retrieving document(s) for an Envelope, see this page: https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeDocuments/. You'll likely use the List Envelope Documents request to get the list of documents in the Envelope, and then subsequently issue a Get Envelope Document request for each document that you want to retrieve.
Additional comments
While you certainly can use REST API requests as I've described above to periodically poll for Envelope (or Recipient) status, and then request document(s) when envelope (and/or recipient) status is completed -- a more efficient alternative would be to use DocuSign Connect, which you could configure to automatically push Envelope status and documents to an endpoint you specify when an Envelope reaches status = completed.
I generate an envelope for the customer to sign as a embedded (captive recipient) so they do not receive an email, instead I redirect them to the new envelope from my app, the intention is that they come back, in a seamless experience.
However what's happening is when they visit the URL, Docusign sends them an unwanted email. So for example if their name is Josh, they will receive an email from Docusign, with
Subject: "Josh viewed Please sign contract X"
Body: Title: "Josh viewed Please sign contract X"
Body: Description: At (time) Josh opened and viewed your documents, Contract X.pdf
This is not a good customer experience. Josh receives a lame email talking about him in the 3rd person. The link in the email requires the customer to register with Docusign which is just a hassle for them, it adds no value whatsoever. They can view the contract within my web-app.
Preferred question
How can I suppress as many emails as possible from Docusign to the customer, using the API? I've examined the API docs but didn't find anything there about suppressing emails for embedded stuff.
Apparently it can be done via the classic preferences. But I always prefer to override these things in code. Is it possible to suppress the emails with options in the API?
Alternative question
I tried adding the following options to the create envelope request, to at least embed an explanation for the customer, to say what the unwanted Docusign emails are about. But only text subject2 appeared. But not in a good way.
I got am email with the subject: "Josh viewed Test subject2"
No custom body appeared un the unwanted email.
recipientEmailNotification: {
emailBody: 'Test body',
emailSubject: 'Test subject'
},
emailBody: 'Test body2',
emailSubject: 'Test subject 2',
EDIT:
Thanks CodingDawg, you've cleared things up for me quite a bit.
You've got a good point there, I may have confusing emails, because my admin email address is the same email address as my first recipient (I realize now it's a bad idea for testing, I'll use a different email address)
EDIT 2
I see now there are email settings in admin preferences, and also in user preferences. Good to know!
I think you are getting confused between Sender and Recipient emails.
After an envelope is sent to an embedded recipient the recipient does not get any emails immediately.
After the Sending App generates a signing link and redirects to the recipient , Sender(not recipient) gets an email saying the "Recipient viewed envelope"
The "Recipient Viewed envelope" email can be suppressed in the senders account preferences. See info for NDSE here , CDSE here
After the Embedded Recipient signs the envelope, the recipient will receive an "Envelope is completed" email
The "Envelope completed" email can be prevented from sending to the recipient by selecting the "Suppress emails to Embedded Signers" checkbox in the sender's account preferences. Please note that this is an Account wide setting and cannot be done at per envelope level. More info here
recipientEmailNotification
The recipientEmailNotification property that you have specified in your request is invalid. Here is a sample json for CreateEnvelope api to set email body/subject at recipient level.
In the following example,
"recipient one" will receive an email with subject "This is recipient one subject".
"recipient two" will receive an email with subject "Email Subject to all recipients"
JSON
{
"status": "sent",
"emailSubject": "Email Subject to all recipients",
"emailBlurb": "Email body to all recipients",
"recipients": {
"signers": [
{
"recipientId": 1,
"email": "recipient1#foobar.com",
"name": "recipient one",
"emailNotification": {
"emailSubject": "This is recipient one subject",
"emailBody": "This is recipient one email body"
}
},
{
"recipientId": 2,
"email": "recipient2#foobar.com",
"name": "recipient two"
}
]
},
"documents": [
{
"documentId": 1,
"fileExtension": "txt",
"name": "Test Document",
"documentBase64": "VGVzdCBEb2N1bWVudA=="
}
],
"emailBody": "envelope level email Body"
}
Friends,
I am using Docusign API and it is working fine. Currently if I send an envelope to more than one customer, Docusign will give status as delivered only after all the recipients viewed the document.
I would like to get status as delivered even if the first recipients opened the document.
Is it possible with the Docusign API?
Thanks in advance.
In DocuSign Envelopes can have status as well as Recipients. For instance, let's say you have an envelope with 2 sequential recipients, the first recipient has signed, and the envelope has been sent to the second recipient. In this scenario, the overall envelope status would be Processing, the first recipient status would be Completed, and the second recipient status would be Delivered (if they have viewed the envelope or Sent if they have not viewed it yet.
See "Recipient Statuses" section on this page from Dev Center
So instead of getting the Envelope status you need to make the API call to get Recipient status. Details of that call are:
GET /accounts/{accountId}/envelopes/{envelopeId}/recipients
Optional query strings: include_tabs={true or false}, include_extended={true or false}
Sample Response:
{
"agents":[]
"carbonCopies":[],
"certifiedDeliveries":[],
"currentRoutingOrder":"String content",
"editors":[],
"inPersonSigners":[],
"intermediaries":[],
"recipientCount":"String content",
"signers":[{
"deliveredDateTime": "String content",
"recipientAuthenticationStatus":{
"(authentication status result)":
"eventTimestamp":"String content"
"status":"String content"
}
},
"recipientId": "String content",
"requireIdLookup": "String content",
"roleName":"String content",
"routingOrder": "String content",
"signedDateTime": "String content",
"status": "String content",
"email": "String content",
"name": "String content" }]
}]
}
See page 191 of DocuSign API Guide for more info
Is there a way to assign tabs to a document, without having a recipient declared?
Situation: We want to have a template for an employee application, and then use the API to fill the fields, assign the recipients, and embed for signing.
When I create the template with no recipient, it doesn't allow me to place any tags. Given that I don't know the recipient until the time I call the API, does that mean I can't place the tabs until then? I really don't want to have to place 50 tabs dynamically.
Thanks in advance.
Chase
DocuSign tabs are always with respect to a given recipient, never the document itself, however I believe you can still accomplish this workflow. If you create a Template through the DocuSign Console you can add a template role without providing any recipient info (i.e. name or email) at that time. Afterwards when you reference this template through a signature request API call you can then supply the actual recipient names and emails in the request and map them to your already configured envelope tabs through the
roleName
property for each recipient.
The very first DocuSign API Walkthrough has code that demonstrates how to do this with just one role, but note that this is just an example and you can have multiple roles.
DocuSign API Walkthroughs
From a high level these are the steps you want to take:
Create a template in the DocuSign Console.
Add document(s), then add at least one recipient but only fill in the role field.
Now on your document you'll see that you can add whatever tabs you want to the envelope, under that role.
Save the template.
Make an API call for requesting a signature, which references the templateId and has the roleName parameter present for your recipient(s). This roleName value should match the role that you saved with the template in step 2.
If you named the role Signer1 for instance, your request body (in JSON format) might look like this:
{
"accountId": "123456",
"emailSubject": "DocuSign API Call - Signature Request from Template",
"emailBlurb": "Sample email body",
"templateId": "B977F511-CAB0-...................",
"templateRoles": [
{
"roleName": "Signer1",
"email": "test#docusign.com",
"name": "John Doe"
}
],
"status": "sent"
}