> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# API usage guidelines

> Learn guidelines and best practices for using Docusign APIs.

This document should be read alongside the Docusign [Developer Terms and Conditions](https://www.docusign.com/company/terms-and-conditions/developers).

The Docusign systems and APIs are designed to work best with well-designed and implemented API applications written by Docusign customers, ISVs, and other partners. If your application does not work well with Docusign, we will attempt to alert you. Whether we were able to contact you or not, if the problem is not fixed expeditiously, then we will limit or deny your application’s access to the Docusign APIs and systems.

Some types of issues may result in immediate suspension of services to your application. This includes, but is not limited to, information security issues, and denial of service attacks.

Here are examples of common application behaviors and how they should be implemented.

## API errors

Your application should never cause Docusign to return an error response (status codes outside the 200-299 range). Your application should log an alert for any error response from Docusign and each should be investigated to determine the root cause and eliminate the problem.

## Status updates

Applications that want updated status information from Docusign should use the webhook notification service either at the account level (Connect) or at the envelope level (eventNotification).

### Webhooks

When receiving [webhook](/platform/webhooks) notifications from Docusign, your computer is the server. Docusign makes POST **requests** to your server.

* Status: your server must be designed to **always** return a 200 status response to Docusign when the message is successfully received. If your application does not need a particular notification message, it should respond with a 200 to Docusign, then discard the message.
* Availability: your server should be designed for 99% or better availability. It can have limited maintenance windows. It should be designed to be available 24 hours a day, 7 days a week. If this is difficult to achieve, you can use a PaaS (cloud) system to receive the messages from Docusign and buffer them for your application. This configuration also enables your application server to receive the notification messages behind your firewall with no changes to your firewall.
* Speed: your server should be designed to respond to each request from Docusign within five seconds. Your server should use an asynchronous architecture: add incoming notification messages to an internal non-volatile queue, then send a 200 response to Docusign. Asynchronously, one or more worker processes should process the messages from the queue.

### Polling

Docusign does support polling with the following restrictions:

* GET requests to any specific URL can be called not more often than once every 15 minutes. For example, obtaining the status of a specific envelope can be done once every 20 minutes, but not once every 10 minutes.
* This limit applies to any **get** or **list** API method for any object: for example, a **list** method for the completed documents of a workflow.
* Your application must not make any additional API polling calls to an object once the object has reached a terminal state. For example, once a transaction is complete or voided, you should no longer poll it, since the transaction will not change in the future.
* You can poll for more than one object at a time. For example, suppose your application polls its active envelopes four times an hour. If your application has 10 active envelopes, then your application can make up to 40 polling requests per hour (four per envelope ID). A better alternative would be to use a **list** method four times an hour and include the 10 envelopes’ IDs in the list method’s request.
* By default, the maximum number of requests that can be made in an hour from all apps associated with an account is 3,000. This includes polling calls. For example, suppose your application sends 400 envelopes per hour and polls each envelope four times per hour. If, on average, your recipients take over an hour to complete each signing request, your application could exceed 3,000 API calls (combined sending and polling) after two hours.

## API call rate

* By default, the maximum number of requests that can be made in an hour from all apps associated with an account is 3,000. You can update this limit for eSignature API calls through the [API limit management](/tools/api-usage-center/limit-management) feature if your account meets certain prerequisites.
* Docusign also has a burst limit of 500 API calls per 30-second period for all apps associated with an account.
* Your applications should not make additional API requests after your account has exceeded its hourly or 30-second burst rate limit. Instead, your applications should make no further calls until the hourly or 30-second reset time has been reached. Your applications should read and act on the `RateLimit` and `BurstLimit` headers that are returned by Docusign. See  [API resource limits](/platform/resource-limits) for more information.

## Inefficient API calls

* Your application should accomplish its goals with the minimum number of API requests. For example, instead of creating a draft envelope, then creating objects within the envelope via additional API calls, then making an API call to send the envelope, it is better to make a single [Envelopes:create](/docs/esign-rest-api/reference/envelopes/envelopes/create) call if you can. Using multiple API calls when one call can achieve the same result wastes resources, uses up your account's budget of API calls per hour faster, and takes longer.
* Your application should not create unused or unnecessary objects within the Docusign system. For example, draft envelope objects should not be created unless they will be sent.
* With eSignature REST API v2.1, downloading multiple objects can often be achieved via a single call. For example, see the `include` query parameter for the [Envelopes:listStatusChanges](/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges) API method. Use the `include` parameter instead of making additional API calls for subsidiary objects.
* For JWT Grant applications: do not call [/oauth/userinfo](/platform/auth/reference/user-info) more often than once per impersonated user per application restart. Do not call it each time the JWT grant flow is used to obtain a new access token for an impersonated user.
* For Authorization Code Grant and Implicit Grant applications, don’t call [/oauth/userinfo](/platform/auth/reference/user-info) more often than once per authentication per user. For example, do not call it when a refresh token is used to obtain a new access token.
* Do not use an OAuth flow unless the previous access token has expired, is about to expire, a different user’s access token is needed, or the application has been restarted. If an application uses JWT Grant and switches between two or more impersonated users, cache the access tokens. Only request a new one when needed.

## Exceeding usage limits

If your account activity regularly exceeds usage limits, you have the following options:

* Visit the [API Usage Center](/tools/api-usage-center) to pinpoint the causes of excess usage, and follow the recommendations you’ll find there to improve efficiency.
* Contact [Docusign Support](https://support.docusign.com/s/contactSupport) for assistance with troubleshooting efficiency issues.
* Use the [API limit management](/tools/api-usage-center/limit-management) feature to update the hourly limit for eSignature API calls.

## Summary

Together, your application and Docusign act as a high-speed, highly reliable system. The Docusign Developer Center has documentation and many code examples to assist you in designing and writing your applications.