I'm using the docusign api and am having some trouble with a query string param. Basically I'm trying to grab the recipient information of an envelope along with the status of the envelope in a single call.
I am able to grab each of information individually with the following api calls and they both work
1.) Envelope endpoint (has a status field with overall envelope status such as Signed, Voided, Declined, etc...):
https://na2.docusign.net/restapi/v2/accounts/:accountId/envelopes/:docusignEnvelopeId/
2.) Envelope/recipients endpoint (has information regarding recipients)
https://na2.docusign.net/restapi/v2/accounts/:accountId/envelopes/:docusignEnvelopeId/recipients
However, I'm trying to see if I can grab these information all within one API call. According to the docs here for the general envelope endpoint, I think I should be able to with a query param
https://developers.docusign.com/esign-rest-api/reference/Envelopes/Envelopes/get#request.
Under the include Optional Query Parameters section, there's a param for "include" which says I can grab recipients from the 1st endpoint. "Specifies additional information about the envelope to return. Enter a comma-separated list, such as tabs,recipients. Valid values are..."
I've been trying to modify the first endpoint with this include param to look something like this...
https://na2.docusign.net/restapi/v2/accounts/:accountId/envelopes/:docusignEnvelopeId?include=recipients
But I have been unable to have recipients show up as well. Was wondering if I'm just typing in the param wrong or if this is not available anymore. Any help would be appreciated!
Thanks :)
The include parameters were added in v2.1 of the eSignature API, so they don't work in v2. Changing your URL to https://na2.docusign.net/restapi/v2.1/accounts/:accountId/envelopes/:docusignEnvelopeId?include=recipients should return the recipient info.
Related
I am using the DocuSign REST Api and noticed that the lifetime of a URL obtained using the EnvelopeViews API (https://developers.docusign.com/esign-rest-api/reference/Envelopes/EnvelopeViews/createRecipient) is only a few minutes. However, I have gotten emails in the past with DocuSign links. How are these links able to be added to an email (and therefore have a longer lifetime)?
Is there a separate API that can be used to get a longer-life link like the one in the email?
For example, here is an email that has a Review Document DocuSign link:
Good question. Here's what you can do.
Your application wants to let Larry sign a document using the
EnvelopeViews::createRecipient API call.
Your application should store the details needed for the API call in your app's database. Something like: envelopeId, signerEmail, clientUserId.
Create a guid for the database record and add it to the database record.
Now you can look up the database record via either the row's key or
via the guid. Ensure that the guid database column is indexed.
Now create a signing url that you will send to Larry. Something like:
https://myapplication.example.com/docusign-ceremony/[guid]
Send the url to Larry
When Larry clicks on the URL:
Your app is invoked
Look up the guid in the url in your database. You should find the
record that you stored there.
Retrieve all of the record's info: envelopeId, signerEmail,
clientUserId.
Call the EnvelopeViews::createRecipient API call with the data
and get back the signing ceremony url (that must be used within
5 minutes)
Redirect the user's browser to the url.
They'll sign the document(s) and then be re-directed back to your
application.
Done.
And guess what? This is pretty much what DocuSign does itself.
The response from Larry K above is correct, you would need to handle this on your side.
These are all the parameters that you can send as part of the request body for the POST {vx}/accounts/{accountid}/envelopes/{envelopeid}/views/recipient API endpoint and there are no options to set the expiration time for the recipient view that you create.
You could look into using PowerForms to see if they fit your needs. With PowerForms you can create a URL that users can click and it will allow them to fill out a specific DocuSign envelope. This might not fit your needs if you need to pre-fill some of the fields with information related to the specific recipient but it might be worth looking at.
PowerForms Documentation:
https://www.docusign.com/features-and-benefits/features/powerforms
Please correct me if I'm wrong but I think that your goal is creating the recipient view URL, creating an email formatted in a specific way and sending that email to the recipients.
If you use the branding feature you could specify the format for your email (if you want to use a specific message) and just send the envelope to your recipients. Once the recipients receive the email they'll see the message in the format that you specified and the link for accessing the envelope would be a regular DocuSign link that doesn't expire.
The link below shows how to create Brands in your account. Specifically signing brands would allow you to set the email content.
If you have multiple email formats you could create multiple brands and just specify the brandId when creating the envelope.
I hope this helps.
Branding:
https://support.docusign.com/guides/ndse-admin-guide-configure-branding
The docusign website allows for me to save a document as a template, but I have not been able to find a way to do this programmatically through the API. Is there a simple way to save a document as a template?
Yes, you can create a Template via the API by issuing this request:
POST /v2/accounts/{accountId}/templates
The API documentation contains details about this operation.
UPDATE
Do I understand correctly that your goal is to create a Template that's based upon an existing DocuSign Document, i.e., to mimic the following functionality in the DocuSign web UI?
If that's the case, then I'm not aware of any single API call that can do this. Instead, I believe you'll need to issue a series of API calls, to retrieve info about the existing Document(s) and then create the new Template using that info:
1) Get information about the existing DocuSign Document (envelope): GET /v2/accounts/{accountId}/envelopes/{envelopeId} (docs)
This operation returns recipient info (including tabs for each recipient) as well as envelope data like email subject, email body, reminders, etc. It also returns a documentsUri property that you can use to get the document(s) that belong to the envelope.
2) Get the list of document(s) that the envelope contains by issuing a GET request to the URI specified by the documentsUri from the prior response. (docs)
This operation returns information about each document in the specified envelope, but does not return document contents.
3) For each document listed in the prior API response, issue a GET request to the URI specified by the uri property for the document. (docs)
4) Finally, create a new Template using the data that you received in response to the previous API requests: POST /v2/accounts/{accountId}/templates (docs)
Note: As a final note -- if you're using one of the DocuSign SDKs, it's possible that there might be a function that you can call to implement this scenario, without having to piece together all of these API calls yourself. I'm not familiar enough with the SDKs to say whether or not they provide this type of functionality, but it'd be worth checking for, if you're using an SDK.
I'm looking to use the DocuSign REST Java API to request a signature from a template, but I'd like to include a specified request id string that I can retrieve via the envelope after the signer completes the form.
Envelope.setTransactionId("") sounded like what I wanted (though I'd rather have something permanent instead of just valid for 7 days as mentioned in the docs), so as an example I called:
envDef.setTransactionId("TRANS12345");
But when I sign the test Envelope and then query it with getEnvelope(...) and call getTransactionId() I get null.
Can anyone point me in the direction of how to properly retrieve the transaction ID, or if there is a better way of adding a permanent specified ID to a signing request?
You can use Envelope Custom Fields aka Document labels to specify additional metadata for an envelope.
See this answer for more information.
I have added textTabs for a signer in an envelope using the DocuSign API.
I would like to request the information which the user has entered into the textTab. How can I do that?
I found the following hint:
Retrieving information from a signed document DocuSign API
But when looking into the REST API documentation it is stated that the API retrieves the original value (originalValue) of the tab when it was sent to the recipient.
That is exactly the behaviour I had discovered.
Does there exist any other method to retrieve the data entered by the signer?
Here are two approaches to get the tab values for an envelope:
1) envelopes/(envelopeID)/recipients?include_tabs=true. This will return all tab values for every recipient on the envelope. It does NOT include the originalValue property of a tab though.
2) envelopes/(envelopeID)/recipients/(recipientID)/tabs. You will need to explicitly hit the tabs endpoint for every recipient. This will display the originalValue property. Example: ../envelopes/5ad452d5-3004-4b8b-b4d1-ef90f02f2c45/recipients/1/tabs
So I'm using REST API for my DocuSign handling, and I have this snippet that checks every 30 mins the status of each envelope, but I'm having hard time find out if there is a way to trigger response (i.e. email) as soon as someone signs the document?
Yes, the DocuSign REST API includes a webhook facility that you can use. When you call Envelopes:Create, include an eventNotification object. In that object you include an internet-accessible URL.
The DocuSign platform will then make HTTPS POSTS to your URL when there is an interesting status change to your envelope. (You define "interesting" status changes as part of the eventNotification object.)
See the eventNotification section in the docs.