When using the DocuSign REST V2 API, doing a GET /v2/accounts/{accountId}/envelopes/{envelopeId} returns an object with 24 properties, mostly URIs, IDs and timestamps.
The documentation for this call (https://docs.docusign.com/esign/restapi/Envelopes/Envelopes/get/) in Examples section has a sub-section called "Get Status About a Specific Envelope " that shows this (24 properties), but it also has a sub-section called "Generic JSON Response" that has a lot more properties and data.
I would like to get a response like the "Generic JSON Response" but I cannot figure out how. Any help would be appreciated.
The Generic JSON Response shows the response that would be returned for an envelope object that has every parameter/feature in use.
In addition, the Generic Response includes some secondary and tertiary data that may not be returned for the standard call.
What data do you want?
If you need an envelope's recipients, use the EnvelopeRecipients::list method. If you want the envelope's documents, there is a separate call for that. Et cetera.
The problem is that returning everything known about an envelope would be a very expensive call for the platform to process. Therefore the data is provided to you in different calls.
Related
Using the EnvelopesApi client, I'm honestly not all that sure where to begin. Do I have to call DeleteDocument() with the DocumentId that I want to replace, and then call UpdateDocuments(), passing in only an envelope definition that only includes the document that I'm replacing it with; or do I have to recreate the envelope definition entirely? Or should I instead just call Update(), passing in the new envelope definition with the correct documents? What is the correct/recommended approach for replacing a document within an envelope that is not completed? Is this documented anywhere?
Thank you
First thing first.
If your envelope was "sent" which means it is no longer in "draft" (created) state, you cannot change it without using the Correct feature.
Correcting an envelope after it was sent is a specific action meant to allow the original sender to make modifications as allowed by law.
In terms of replacing a document in an envelope, you can use this method:
PUT
/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}
Assuming you know the accountId, envelopeId, and documentId
See more information about this endpoint in Developer Center
Is there a way that I can provide any custom document metadata when adding documents to my DocuSign envelopes when using the REST API?
DocuSign appear to enforce the use of a positive integer for the DocumentId's we provide in the envelope. Whilst we are indeed using a positive integer, sometimes, there is some additional info that we need to supply, which we would like to come back in the DocuSign webhook events for specific documents.
I've had a look at the Document object but can't see anything obvious that I could use. An example would be simply providing a true/false along with a specific document, which I can inspect when I receive the DS webhook events.
At the moment, the only workaround I can think of is to add an Envelope Custom Field which contains any of my DocumentId's where 'true' is applicable, which feels like a bit of a shoddy solution, and I don't know if there's a character limit in those Envelope Custom Fields, which could break such a workaround.
Custom envelope text fields give you complete flexibility on providing meta-data that you can get back from the webhook. Here is some information about this:
This is how you create a custom field for an envelope:
https://developers.docusign.com/docs/esign-rest-api/reference/Envelopes/EnvelopeCustomFields/create/
This article shows code examples in 7 languagues on how to get the custom fields values :
https://developers.docusign.com/docs/esign-rest-api/how-to/get-envelope-custom-field-values/
It seems that docusign only supports downloading the signed documents as PDF instead of JSON.
I need to 'read' the filled fields of the documents (the document has some fields to fill in).
I can upload the document as JSON and it gets parsed, so why can't I donwload it as JSON?
How do companies normally handle the field values?
Thanks!
You don't need the actual PDF document to get the values, you need to parse the call coming back from DocuSign since that has total envelope data. The webhooks for notification contains the data and you can parse that to retrieve the envelope data.
Do you know if its also possible with a GET call instead of the webhook? It could be the server is down etc, so I can't imagine DocuSign does have something like GET:envelope/:id/data or something.. But really cannot find anything like it
Yes. You can either use a GET call (included below) any time you want to get envelope data or you can set up the webhooks so that DocuSign will send you updates whenever it has one!
The following GET call retrieve envelope data from {{envelopeId}}. By parsing the response from the call you can retrieve all information that was filled on the envelope.
{{baseUrl}}/envelopes/{{envelopeId}}/recipients?include_tabs=true
I hope this helps.
P.S. Summarized our comments to have a complete answer.
The PDF format is, for lack of better words, a complicated jumble of compiled data that can be difficult to parse. What it appears docusign will do is take the data provided and fill the PDF document fields that are previously identified.
With docusign returning the PDF, you will need to parse the PDF input fields to receive the field values. There are several libraries that can be used to parse the various form fields and do what you would like. Check out:
https://www.npmjs.com/package/pdfreader
https://www.npmjs.com/package/pdf2json
I am sure there are more that would work for you as well if you look around if these don't work for you.
I am writing a simple software that needs to:
Connect to an IMAP server
Download all unread messages
Store each message's body, and attachment. I prefer the body as text.
Mark them as read
I am reading https://github.com/mscdex/node-imap; however, a message can be in multiple parts, and that's where I am lost. For example, when it's multi-part, what is the part that is guaranteed to be the actual email body?
Or, even better, is there a wrapper out there that will just return a nice "message" object, all neatly fetched and prepared for me? Something with the usual headers (from, to, etc.), to body, and a bunch of pre-decoded attachment?
Merc.
To answer the good part of your question: No part is guaranteed to be "the email body", you can legally send a message without text. I've seen software that'll send attachment-only mail when the user adds an attachment but leaves the mail body field empty. The way to distinguish between inline bodies and attachments is to look at the content-disposition field, and if that's not present, assume inline for text/* and attachment for other types. (Yes, this also means that there may be more than one inline body. Apple Mail is fond of sending that, for instance.)
The other part of your question is a FAQ and an easy one, and yes, there's much software to build that message object. Approximately 100% of client libraries can do that. Search your documentation for "bodystructure", that's the name of the IMAP fetch item they retrieve and parse in order to build the structure you want.
There appears to be two ways I can gather status information about individual recipients on an envelope:
GET - v2/accounts/:accountId/envelopes/:envelopeId/recipients
GET - v2/accounts/:accountId/envelopes/:envelopeId/audit_events
Unfortunately, each of these suffers from a separate limitation that is making it difficult for me to use either.
This API call returns two DateTime values of interest: deliveredDateTime and signedDateTime. I am able to call and use this API successfully. However, it appears to me that deliveredDateTime is not specified until the user actually clicks the email link AND clicks the review documents button on the signer view. Since what I was actually interested in might be better described as sentDateTime, deliveredDateTime doesn't appear to work for my needs.
This API call returns a detailed list of all events that have transpired on the envelope, including individual receipient status updates. However, the data format is such that in order to tie the result data back to recipients, I have to do string matches on the recipient name. I'd prefer to do the match based on email or, better still, recipientID, but the audit log entries for "sent invitations" and "signed" don't contain these fields. Here is an example (click here to view larger):
Is there an API call other than these two that I can use? Is there a way to get additional data in the audit event API call?
Thank you in advance,
Andrew
I don't believe there's a way to get additional data from the audit_events call since the DocuSign API documentation (which is up to date) indicates that call has no parameters (other than the envelopeId in the URL).
I think you're stuck with doing a string comparison on the userName value to identify/link your recipients, however I want to point out that once you do that you can then link to their unique recipientGuid through the first api call you've highlighted here.
For instance, the /audit_events API call seems to achieve what you want and has all the info you need, however it identifies the recipients through their userNames. If you then make a call on the same envelope and check the response from the /recipients URI, it contains the name, email, recipientId, and recipientGuid for each and every recipient in the envelope. Match the user names and you now have access to their IDs, etc.
So in the end I don't believe there's one API call to achieve this but you can solve by doing one string compare and combining the results from the API calls you've highlighted.