I tried calling DocuSign sales and support (transferred around 3 times) and no one could give me a straight answer on this. Their "support" actually told be to try stackoverflow, so here I am...
I'm looking at their API pricing levels here: https://www.docusign.com/products-and-pricing/api-plans-b
If I have the Intermediate API, can I make the following API requests?
GET /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}
GET /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/form_data
The part that's throwing me for a loop is the DocuSign Connect feature in the Advanced API plan. The description of it is:
The DocuSign Connect module lets you configure webhooks for envelope events and recipient actions for some or all users in your account. It can also be used to transport the completed documents back to your app or website and to retrieve any form field data entered by your recipients.
I don't need the webhooks, but I need to be able to get the completed documents as PDFs and get the form field data. Do I really need the DocuSign Connect feature for that?
You will be fine with the intermediate plan. Here is the basic distinction between polling and Connect - With Connect, we will proactively notify YOU when key envelope events occur.
Otherwise, it's up to you to call GET /envelopes and/or GET /form_data to retrieve that information. Be wary of the resource limits when you poll.
As a quick aside, instead of making two requests to retrive that information, just make one - GET /envelopes?include=recipients,tabs. This will provide you all the information you seek in one request.
The important excerpt from that guide:
You may not exceed one GET request per unique envelope endpoint per 15
minutes. If you exceed this limit the request will not fail, but it
will be flagged as a violation of rate limits which can cause your app
to fail review to go-live review.
For example, the following transactions violate API rules due to the repeated GET requests to the first document and second recipient:
[12:00:00] POST /accounts/12345/envelopes
[12:01:00] GET /accounts/12345/envelopes/AAA/documents/1
[12:02:00] GET /accounts/12345/envelopes/AAA/recipients/2
[12:03:00] POST /accounts/12345/envelopes
[12:04:00] GET /accounts/12345/envelopes/AAA/documents/1 *
[12:05:00] GET /accounts/12345/envelopes/AAA/recipients/2 *
However, the following set of requests comply with API rules and limits and would not be flagged by the platform:
[12:00:00] POST /accounts/12345/envelopes
[12:01:00] GET /accounts/12345/envelopes/AAA
[12:16:00] GET /accounts/12345/envelopes/AAA
[12:17:00] GET /accounts/12345/envelopes/AAA/documents/1
[12:32:00] GET /accounts/12345/envelopes/AAA/documents/1
[12:40:00] PUT /accounts/12345/envelopes/AAA/recipients/1
[12:41:00] PUT /accounts/12345/envelopes/AAA/recipients/1
Related
I can see the below point in docusign documentation https://developers.docusign.com/docs/esign-rest-api/esign101/rules-and-limits/
2. Apps are limited to one GET status request per unique envelope per 15 minutes. If you exceed this limit, the request will not fail, but it will be flagged as a violation of rate limits, which can cause your app to fail review to go-live. To avoid exceeding this limit, design your app to poll at 20-minute intervals rather than 15 or, rather than polling for envelope status, your integration can subscribe to Connect to get status updates for the envelope.
My requirement is to poll the documents for each user using API:
GET https://demo.docusign.net/restapi/v2.1/accounts/<account_id>/envelopes?count=10&from_date=2021-10-21T04:38:51.0930000Z&include=recipients&order_by=last_modified&order=asc&folder_types=normal,inbox,sentitems,draft&start_position=0
and there documents using API:
GET https://demo.docusign.net/restapi/v2.1/accounts/<account_id>/envelopes/<envelope_id>/documents
and I have multiple user connection with same account Id, hitting these two APIs.
will it be flagged as rate limit violation? I have tried these GET api again and again but I can't see this violation status on my client? how can get update of this if in case it happens on my prod instance?
What is the goal of this API call?
GET https://demo.docusign.net/restapi/v2.1/accounts/<account_id>/envelopes?count=10&
from_date=2021-10-21T04:38:51.0930000Z&include=recipients&
order_by=last_modified&order=asc&
folder_types=normal,inbox,sentitems,draft&start_position=0
Is it to monitor incoming envelopes? If so you can use Recipient Connect to receive webhook notifications.
Otherwise, for a given DocuSign user, you can make the API call once every 15 minutes or less often.
You cannot make the call more often than once per 15 minutes per associated user. If your app uses a "system user" such as finance#your-company.com then you cannot call it more than once per 15 minutes since the results would not change.
And what is the goal of this API call?
GET https://demo.docusign.net/restapi/v2.1/accounts/<account_id>/
envelopes/<envelope_id>/documents
The documents in an envelope are generally not going to change.
More often, apps want to know when an envelope has completed, and then download the docs.
Update
The polling limits are:
per user
results must be expected to change
This means that you cannot poll after an envelope reaches a terminal state. IE only poll if the envelope is in the sent or delivered states.
And it is still not clear to me why an envelope's documents will change.
If you want to provide the current version of the envelope's documents to your application's user, give them a button to download the documents. Don't poll for them.
Finally remember the limit of 1,000 API calls per hour per account for your application. Your application will NOT be approved for additional API calls per hour with this type of polling activity.
I've been working with the DocuSign API for some time now, and it's all fine, but when the signer refuses to sign, I get a rejection message using "EnvelopeRecipients:: List".
However, frequent use of the API is prohibited in the go-Live instructions.What should I do?
enter link description here
enter image description here
RecipientViewRequest viewOptions = new RecipientViewRequest
{
ReturnUrl = returnUrl,
ClientUserId = this.CurrentUserID,//DSConfig.ClientID,
AuthenticationMethod = "none",
UserName = displayName,
Email = userEmail
};
// Use the SDK to obtain a Recipient View URL
var envelopesApi = GetEnvelopesApi();
ViewUrl viewUrl = envelopesApi.CreateRecipientView(JwtAuthClient.JwtAuth.Account.AccountId, envelopeId, viewOptions);
You could use DocuSign Connect webhook or if you're using embedded signing, it's in the URL that goes back to your app after the user finished signing.
" frequent use of the API is prohibited" is not accurate. Polling is what is bad/not allowed. "frequent" is relative. If your app need to make more API calls - you may make more API calls. There are limits etc. but you don't want to also go overboard with the notion you cannot make API calls.
You're facing limitation issues because of bad implementation.
I know it's too late but I recently work on DocuSign API and randomly found this question, that's why decide to answer it for other people if they come to this question to find the solution.
The Latest DocuSign API version is 2.1 and I'll only talk about that version.
In this version, either you call via SDK or your custom code List API Call
end-point has many options which we can use to optimize the Envelope check status.
count, start_position, and continuation_token parameters are useful when you have a large number of envelopes on the Cloud which status do you want to check (include decline) to split the result in chunks or you can say page wise. It will help you to manage frequent call limitation issues like you can filter only those envelopes which status you want to check with further options and fetch envelopes in a bunch instead of each envelope status will help you to reduce the number of calls to DocuSign.
(I'm not going to train you on how you can write code as this is not a platform for that)
For the case which is mentioned in the question, the same API end-point will be useful to fetch only declined envelopes with messages.
Like for that purpose you just need to pass "declined" against the status parameter which is useful to filter cloud envelops status-wise. To include declined message with the response, you need to pass "recipients" against the "include" parameter, which appends the Recipient entity with each envelope object where you can filter out the declined message. "DeclinedReason" or "VoidedReason" there are two properties which can return a decline message with this call. If you want to see the complete schema of the envelope entity, you can go through same link List API Call
In short, to solve the limitation issue you can use "listStatusChanges" end-point which has too many optional parameters which you can utilize as per your need but the performance depends on how you utilize it.
PS: Webhook is a better option to sync data between two services in optimize way or without any calling limitation, my answer is only for those who don't want to use webhook.
How many DocuSign envelope statuses can I get at a time by calling the API
PUT /restapi/v2.1/accounts/{accountId}/envelopes/status?envelope_ids=[list_of_ids]
I have a bulk number of envelope Ids and it is increasing day by day. What I am going to do is, I am going to pull all the envelope statuses (except the voided and completed envelopes) in a scheduler manner.
I have not found anything or I have missed in the documentation. Is there a limitation in docusign with the number or request size ?
There are two limits: the max length of a URL including its query parameters, and the max envelope ids for the call.
Avoiding the URL length limit: As documented, you can set the query parameter to a special value: envelope_ids=request_body. In this case, the method uses the envelope IDs in the request body.
From the documentation:
envelope_ids query parameter -- The envelope IDs to include in the results.
The value of this property can be:
A comma-separated list of envelope IDs. [or]
The special value request_body. In this case, the method uses the envelope IDs in the request body.
I don't know what the second limit is.
As an alternative, consider setting up a webhook. You can receive the webhook notifications of completed envelopes from behind the firewall (without changing the firewall) by using an intermediate queuing system.
Example code for AWS, Azure, and Google Cloud is available for C#, Java, PHP, Python, and Node.js. See the Connect-* repositories in github.com/docusign
I wan't to fetch only messages that are only internal to organization.
Right now the way i see is fetch domains first then for each message see if from/sender domain belongs to that message , based on that differentiate.
But this is lengthy process and not a foolproof technique.
Is there any GRAPH API query i can use which readily provides this ?
It does not apear that the REST API queries for Office 365 includes this information directly in the messages. From the Version 2.0 And the Beta this is not included in message output.
However, it looks like you might be able to get it from the REST API via the headers.
Try the following query:
https://graph.microsoft.com/beta/me/messages?$select=internetMessageHeaders&$top=1
This takes top one messages and shows you the email header of the message.
In the header look for X-OriginatorOrg. The value should be the main domain of your organisation.
Alternatively you can look at the X-MS-Exchange-Organization-MessageDirectionalityheader. If the value here is Originating it should come from inside your own organisation.
Using DocuSign's REST API, is there a way to retrieve a list of all envelope Ids from an account where the envelopes have a completed status and originated from a specific power form?
I've tried using the follow call and still see all completed envelopes after 9/12 regardless of where they originated from:
GET https://demo.docusign.net/restapi/v2/accounts/1655678/envelopes?from_date=2016-09-12&powerformids=2fc0a56d-f6c7-4e96-be93-258d0c038e3c&status=completed HTTP/1.1
The best working solution I have now is to add a custom field to the envelope and filter on it using the custom_field parameter. This requires additional setup from users and is not optimal.
Thanks.
Have you looked at DocuSign Connect for this? If you setup a specific user for your Powerform, Connect can publish events to you for just the envelopes created from that user. Then you wouldn't even need to make calls to get the Envelope IDs (or even other information).
Your idea of adding a custom field on the template level is the best way to go. It will help return accurate results, though I would agree it adds some overhead/upkeep during template/powerform creation.
The powerformids parameter you are including in your sample is not a supporter parameter and is simply being ignored.