There is a documentation about possible envelop status value from docusign for a given envelope.
Howver i am trying to understand if there are any documentation which lists out the possible "Action" value from docusign in the "Audit_event" REST API method.
The reaosn is I am storing the audit events locally to avoid multiple API calls and i wanted to account for all the possible action values.
Thanks for reading
Since there were any documentation provided, i am including the staus i have seen based on my reverse engg
Registered
Sent Invitations
Printable Copy Delivered
Printable Copy Attached to Email
AccessCode Passed
AccessCode Failed
Viewed
Signed
Approved
Resent
Voided
Declined
Correction Initiated
Correction Cancelled
Viewed In-Session
Corrected
I've never seen any documentation for possible values of the action property within a GET Envelope Audit Events response -- to the best of my knowledge, none exists. You might be stuck having to 'reverse engineer' to determine possible values. i.e., create envelopes via the DocuSign web console, act on them in a variety of ways (both as Sender and as Recipient) -- for example: Send Envelope, Void Envelope, Decline Envelope, Sign Envelope, View Envelope, Pass Signer Authentication, Fail Signer Authentication, etc. etc. etc. -- and then examine the corresponding action values that appear in the GET Envelope Audit Events response for those Envelopes.
Obviously this approach is not ideal, since someone fairly new to DocuSign won't necessarily know all of things that can be done with an Envelope, in order to trigger the various action values in the API response. Perhaps someone from DocuSign will see this post and chime in with a list of all possible values...or better yet, add this info to the API Guide one day soon.
Related
In certain circumstances we would like to automate the forwarding of completed Docusign contracts to certain new recipients, possibly adding another page. Is there a way to do that with the REST API, or does that have to be done manually?
The short answer is Yes.
In DocuSign-speak, "completed" means that the envelope (transaction) has reached its final stage. No more changes, it's frozen and saved in the DocuSign platform.
Also, note that virtually anything you can do via the DocuSign web app can also be done programmatically via one of DocuSign's APIs.
So you have two options:
Send the first envelope to someone else as a new envelope
After the first envelope is complete, your API program could analyse it to see if it needs some additional recipients. If so, your API program could start a new envelope transaction that includes the completed (signed) document, possibly the first envelope's certificate of completion, along with the new documents to be signed (or not) and new recipients.
You could include the first set of documents (from the first envelope) either as supplemental documents to the new envelope or as regular documents within the new envelope. To obtain the documents from the first envelope, your application would download them from DocuSign and then upload them for the new envelope.
A live "supplemental" documents example.
A envelope is optionally sent to additional recipients
An alternative is to have one envelope and optionally programmatically send it to additional signers with, perhaps, additional documents for the new signers.
This might be a bit trickier to program with the DocuSign eSign APIs but is certainly doable.
After the last "original" signer has completed signing, you can pause the workflow.
Once the workflow is paused, your application can again analyse the document to see if more recipients need to sign, an additional document needs to be added, etc. Then your API program uses the API to update the envelope as needed, including adding additional recipients (who may or may not be signers). This is called "correcting" the envelope. Then your program resumes the envelope's workflow.
Your program should be notified that the envelope has paused by using the Connect webhook feature, either at the account or envelope level.
If you have more questions about this answer, please open new questions on StackOverflow. Make each question as specific as you can. Thank you.
In my returnUrl handler, I am using list documents.
In the returned array, how can I figure out if the document has been signed or not?
Thanks!
Your return url handler will be called with a query parameter event as discussed in Inbar's answer.
But you should not use the query parameter for making business decisions since a bad guy could easily call your return url and simply tack on an event=signing_complete query parameter--spoofing your application.
Instead, when your application needs to know if the envelope has been signed or not, it has two categories of options:
Ask DocuSign
Your app can call the Envelopes::get method to determine the current status of the envelope. Other API methods can also be used for this functionality.
Design your app such that you do not call DocuSign about a particular envelope more often than once every 15 minutes since such behavior is considered polling and is not allowed.
Webhook: DocuSign will call your app
You can set up a webhook with DocuSign so that the eSignature platform will call your application when the envelope is complete (signed by all the signers, etc).
Use the DocuSign webhook HMAC feature to guarantee that the notification message came from DocuSign (was not spoofed) and that it was not altered in transmission.
By using AWS or equivalent, you can easily receive the notification messages behind the firewall, with no firewall changes. And AWS will not charge you for the first million notification messages per month. See the connect-* repos on github.com/docusign
Dashboards
If your app wants to present a dashboard to a business decision maker about the status of your envelopes, then relying on the event query parameter is fine. But before your app does anything that costs real money, eg initiate goods or services to be provided to a customer, make sure that the envelope has been signed by using one of the two techniques above.
The URL you get back from DocuSign has an event parameter and looks like this:
http://www.acme.com?event=signing_complete
signing_complete means it was signed.
https://developers.docusign.com/esign-rest-api/guides/features/embedding has the full list of other events in the "Determining Recipient Action" section of the article.
I am using Remote Signing with the DocuSign api, but I want to know how to determine what action the recipient took (i.e. they signed, declined to sign, viewed, etc). How do I do this?
You want the status of the envelopes you sent?
Best technique is to create a webhook and have DocuSign call your server when the envelope's status changes.
You can create DocuSign notification message subscriptions at either the account level or at the individual envelope level.
See this blog entry for more info. Ask additional questions on StackOverflow if you have any difficulties.
I've already been successfully using the envelope eventNotification webhooks to receive status updates for various envelope and signer events (Sent, Delivered, Completed, etc.), but I'm trying to solve one last event case: adding and removing signers from the envelope.
Suppose in a situation where envelopes are shared among multiple people in a company:
1. Someone creates an envelope through the API, and adds 3 signers.
2. Someone else makes corrections to the envelope using DocuSign's web site, and removes a signer...
Is there any way for my app to know that action #2 took place? Or do I have to wait for one of the regular signer events to take place before I will know that the signers on the envelope have changed?
Connect event triggers for the start and finish of Envelope Correct are a good idea. You'd use the finish trigger to figure out what has happened.
This enhancement request is internally logged at DocuSign as CONNECT-510.
Ask your DocuSign Account Executive or Account Manager to add your organization's interest in the enhancement. It is not yet scheduled to be released, other Connect architectural work is needed first.
The history of the envelope, including correct operations is available from Envelopes: listAuditEvents. You could use that today to see if someone is correcting the envelopes you're interested in.
We have multiple recipients per envelope and the signing order is set. Can we get the envelope based on the status of individual recipients?. I don't see anything that we can do to achieve this through ListStatusChangesOptions. I know that we can achieve this by listRecipients but this did not give us an option to set parameters to limit the data, like ListStatusChangesOptions.
I want to reduce the API call limit, if there is an option to directly limit the data sent from DocuSign based on the status of the individual recipients.
Eg: Get all the Envelopes whose recipient1 status is completed.
Instead of getting more than required envelopes through listStatusChanges and limiting them by using listRecipients
No, there is no API call to fetch envelope details based on recipient status. Instead I would propose to use DocuSign Connect. It has trigger event of Recipient Signed, so once recipient has signed you will get a message from DocuSign with envelope details like envelopeId, which recipient Signed it etc, and this will save a lot of your API calls and DocuSign Connect is the recommended way from DocuSign instead of doing polling. You can learn more about DS Connect here,
https://www.docusign.com/supportdocs/ndse-admin-guide/Content/custom-connect-configuration.htm
https://www.docusign.com/supportdocs/pdf/connect-guide.pdf