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
Related
We have a template has the following signing flow:
flow we want
Below is how we send the parameters:
{
"emailSubject": "Test company - Custom Rates Letter",
"emailBlurb": null,
"status": "sent",
"templateRoles": [
{
"roleName": "Paticipant B",
"name": "Paticipant B",
"email": "paticipantB#example.com"
},
{
"email": "paticipantA#example.com",
"name": "Paticipant A",
"roleName": "Paticipant A"
}
],
"templateId": "xxxxxxx-yyyy-zzzz-aaaaa-bbbbbbbbb"
}
However, the actual flow we get is not what we configured in the template. It's as followed:
flow we actually get
We want participant A to receive 3 copies: (1) the original unsigned contract (2) the contract signed only by participant B (3) the contract signed by all parties. However, participant A only receives (1) and is not able to receive (2) and (3).
I have tried many other parameters but all don't work. Could you give me some help on this? We want the actual flow to be the same as the flow configured in template. Thanks.
DocuSign does not support this type of workflow, i.e putting same roleName at different places. You need to have different roleName (eg, Participant A1, Participant A2 etc) in your Workflow, then pass same Recipient Name/Email for each roleName.
Or if you want to put same recipient multiple times in the workflow just for notification, then I would request you to consider using DocuSign Connect, once you receive an XML message from DocuSign on your subscribed event then send an email from your Email Server to the concerned person with the notification details.
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"
}
I am trying to implement a DocuSign API app to send documents to our clients for e-signature. In my application, I need to send one document to each client for e-signature. For example, an agreement doc where user will sign and agree to our terms and conditions.
So I will be sending the same document to each client and I assume I will be receiving a unique envelopeId for each individual request.
So how do you keep track of which envelopeId is associated with which user?
Can you send a custom tag in the request and receive it back in response to track it?
Most DocuSign users build a fully functional integration.
Integration such as Salesforce, CRM and other products that integrate DocuSign into their system track it either through an Envelope Custom Field (with their internal application record information) or they document the envelopeId responses and store them in their application.
Either way will work out just the same, it's all on how you want your integration to work.
Here is a quick sample call on how to create an envelope from a template with a text custom field
{
"emailSubject": "Just a test envelope",
"status": "sent",
"customFields": {
"textCustomFields": [
{
"name": "InternalToolNumber",
"required": true,
"show": false,
"value": 123456789
}
]
},
"templateId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"templateRoles": [
{
"email": "john.doe#emaildomain.com",
"name": "John Doe",
"roleName": "Signer 1"
}
]
}
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.