A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The DocuSign API is how an app or AI agent works with a DocuSign account: creating an envelope from documents, sending it to recipients for signature, checking who has signed, downloading the completed file, and building reusable templates. Access is granted through an OAuth access token whose scopes decide what it can do, and because one broad scope covers nearly every signing action, the real boundary is the account and which user the token represents. DocuSign can also push an event to a registered endpoint when an envelope or recipient changes.
How an app or AI agent connects to DocuSign determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes DocuSign actions to agents, and each is governed by the token behind it and the scopes that token carries.
The eSignature REST API answers under the account's regional host, with the version carried in the path as v2.1 (for example /restapi/v2.1/accounts/{accountId}/envelopes). A call authenticates with an OAuth 2.0 access token in a Bearer header, and the account ID and base URI come from the OAuth userinfo response.
DocuSign publishes an official Model Context Protocol server, in open beta on developer and production accounts, at https://mcp-d.docusign.com/mcp. It lets an agent create and send envelopes, send from templates, check envelope and recipient status, manage bulk send lists, and query agreement context through Intelligent Agreement Management, all over OAuth.
DocuSign Connect POSTs an event payload to a registered HTTPS endpoint when an envelope or recipient changes. The endpoint can be configured account-wide in DocuSign Admin or set per envelope through the eventNotification object, and the receiver can require an HMAC signature to confirm the payload came from DocuSign.
The standard OAuth 2.0 authorization-code flow, where a user signs in to DocuSign and consents, and the integration exchanges the returned code for an access token that acts as that user. It suits an app where a real person is present to grant access.
A service-integration flow where the app signs a JSON Web Token with its private key and impersonates a chosen user, with no person present. It needs the signature and impersonation scopes, and one-time consent from each user it impersonates. It suits an unattended agent or backend job.
The DocuSign API is split into areas an agent can act on, like envelopes, recipients, documents, templates, and the embedded signing and sending views. Most of these share one broad scope, so the boundary that matters is set at the account and the access token, not by separate per-area permissions.
Create, send, read, and update envelopes, the container for the documents and recipients in a signing request, and list envelopes by status.
List, add, update, and remove the people who receive an envelope, and resend the notification to them.
List the documents on an envelope, download a single document or the combined PDF, and add or replace documents on a draft.
Generate the short-lived URLs that embed the DocuSign signing, sending, correcting, or console screens inside another app.
List, read, and create reusable templates, and apply a template to an envelope.
List folders and the envelopes inside them, and move envelopes between folders.
Read account information, settings, and the list of users on the account.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
EnvelopesCreate, send, read, and update envelopes, the container for the documents and recipients in a signing request, and list envelopes by status.5 | ||||||
| POST | /restapi/v2.1/accounts/{accountId}/envelopes | Create an envelope and send it for signature, or create it as a draft. | write | signature | Current | |
The signature scope covers nearly every eSignature write, so it cannot be narrowed to read-only or to a single envelope at the DocuSign layer. Setting status to 'sent' sends immediately; 'created' makes a draft. Acts onenvelope Permission (capability) signatureVersionAvailable since the API’s base version Webhook event envelope-sentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId} | Get the status and details of a single envelope. | read | signature | Current | |
The signature scope grants both reading and writing; DocuSign does not offer a read-only eSignature scope. Acts onenvelope Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/envelopes | Search envelopes by status, date range, recipient, and other filters. | read | signature | Current | |
Requires at least one of from_date, envelope_ids, or transaction_ids; omitting all of them returns an INVALID_REQUEST_PARAMETER error. Subject to the per-account burst limit on repeated polling. Acts onenvelope Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /restapi/v2.1/accounts/{accountId}/envelopes/status | Get the status of a set of envelopes named by ID in the request body. | read | signature | Current | |
Read-only despite the PUT verb; the body carries the envelope IDs to look up rather than changing data. Acts onenvelope Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId} | Update a draft envelope, send a draft, or void a sent envelope by setting its status. | write | signature | Current | |
Setting status to 'voided' cancels a sent envelope and notifies recipients; setting a draft to 'sent' sends it. Acts onenvelope Permission (capability) signatureVersionAvailable since the API’s base version Webhook event envelope-voidedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RecipientsList, add, update, and remove the people who receive an envelope, and resend the notification to them.4 | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients | List the recipients on an envelope and their signing status. | read | signature | Current | |
Returns each recipient's routing order, status, and identity details. Acts onrecipient Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients | Add one or more recipients to an envelope. | write | signature | Current | |
On a sent envelope, adding a recipient with resend_envelope set emails them straight away. Acts onrecipient Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients | Update recipients on an envelope, and optionally resend the signing notification. | write | signature | Current | |
Passing resend_envelope=true re-sends real email notifications to the named recipients. Acts onrecipient Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients | Remove one or more recipients from an envelope. | write | signature | Current | |
Removing a recipient from a sent envelope changes who is required to sign. Acts onrecipient Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DocumentsList the documents on an envelope, download a single document or the combined PDF, and add or replace documents on a draft.3 | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents | List the documents on an envelope. | read | signature | Current | |
Returns document metadata, not the file content; use getDocument to download a file. Acts ondocument Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId} | Download a single document, or the combined PDF when documentId is 'combined'. | read | signature | Current | |
Returns the full document content, including signed pages once the envelope is complete. Acts ondocument Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId} | Add or replace a document on a draft envelope. | write | signature | Current | |
The Content-Type must name the file's real type, such as application/pdf. Acts ondocument Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Signing & sending viewsGenerate the short-lived URLs that embed the DocuSign signing, sending, correcting, or console screens inside another app.3 | ||||||
| POST | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/recipient | Get a short-lived URL that embeds the signing screen for a recipient (embedded signing). | write | signature | Current | |
The returned URL lets the holder sign the real envelope, so it is single-use and expires within minutes. Acts onview Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/sender | Get a URL that embeds the sending screen for a draft envelope (embedded sending). | write | signature | Current | |
Used on a draft envelope before it is sent. Acts onview Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /restapi/v2.1/accounts/{accountId}/views/console | Get a URL that embeds the DocuSign web console (the account UI) for a user. | write | signature | Current | |
Returns a signed-in session into the full DocuSign UI for the named user. Acts onview Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TemplatesList, read, and create reusable templates, and apply a template to an envelope.4 | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/templates | List the templates on the account, with optional filters. | read | signature | Current | |
Returns shared and personal templates the authenticated user can see. Acts ontemplate Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/templates/{templateId} | Get a single template's definition. | read | signature | Current | |
Returns the template's documents, recipient roles, and fields. Acts ontemplate Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /restapi/v2.1/accounts/{accountId}/templates | Create a reusable template. | write | signature | Current | |
A new template can be shared with other users on the account. Acts ontemplate Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/templates | Apply a template to an existing envelope. | write | signature | Current | |
Adds the template's documents, recipients, and fields onto the envelope. Acts ontemplate Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FoldersList folders and the envelopes inside them, and move envelopes between folders.3 | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/folders | List the folders on the account. | read | signature | Current | |
Folders organize envelopes and templates for the account. Acts onfolder Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/folders/{folderId} | List the envelopes inside a folder. | read | signature | Current | |
Returns the envelopes contained in the named folder. Acts onfolder Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /restapi/v2.1/accounts/{accountId}/folders/{folderId} | Move one or more envelopes into a folder. | write | signature | Current | |
Moving an envelope changes where it is filed for the whole account. Acts onfolder Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountRead account information, settings, and the list of users on the account.2 | ||||||
| GET | /restapi/v2.1/accounts/{accountId} | Get account information, including plan, billing, and settings summary. | read | signature | Current | |
Returns account-level configuration; reading the full user list needs the user_read scope on top of signature. Acts onaccount Permission (capability) signatureVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v2.1/accounts/{accountId}/users | List the users on the account. | read | user_read | Current | |
Reading the user directory needs the user_read scope, separate from the signature scope used for envelopes. Acts onuser Permission (capability) user_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DocuSign Connect can notify an app or AI agent when something happens to an envelope or a recipient, instead of the app repeatedly asking. It posts a payload describing the change to a registered HTTPS endpoint for the events that have been chosen.
| Event | What it signals | Triggered by |
|---|---|---|
envelope-sent | Fires when an envelope is sent and the notification email goes to the first recipient in the routing order. | /restapi/v2.1/accounts/{accountId}/envelopes |
envelope-delivered | Fires when a recipient opens an envelope and views the documents for the first time. | In-app only |
envelope-completed | Fires when every recipient has finished their action and the envelope is complete. | In-app only |
envelope-declined | Fires when a recipient declines to sign, which ends the envelope. | In-app only |
envelope-voided | Fires when an envelope is voided, either by a sender or automatically on expiry. | /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId} |
recipient-sent | Fires when the notification email is sent to a particular recipient. | In-app only |
recipient-completed | Fires when a recipient finishes their action on the envelope, usually by signing. | In-app only |
recipient-declined | Fires when a recipient declines to sign the envelope. | In-app only |
DocuSign limits how fast an app or AI agent can call, through an hourly request quota set per account and a separate short-window burst limit on top.
DocuSign meters requests per account, not per method. The default ceiling is 3,000 requests per hour across every app on the account, with a separate burst limit of 500 calls in any 30-second window in production. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, where the reset value is a Unix epoch time, though the headers are not present on every response. Going over returns HTTP 429. Repeated polling of the same envelope can trip a separate burst polling limit, so DocuSign recommends Connect webhooks instead of tight status polling. An account that meets the prerequisites can raise the hourly ceiling through the API limit management tool.
List endpoints page through results with start_position and count, where count sets the page size and the response reports result_set_size, total_set_count, and the next and previous positions. Envelope and template searches also take filters such as a from_date and to_date range, a status filter, and a search_text term to narrow the set rather than page through everything.
Envelopes have document and recipient ceilings rather than a single payload size: an envelope holds up to about 2,000 documents and 1,000 recipients, an individual document is capped at roughly 25 MB, and an envelope totals up to about 50 MB of documents. A document download returns the full file content, and the combined download merges every document into one PDF.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST_PARAMETER | The request held an invalid or malformed parameter, like an ID in the wrong format, a body that does not match the expected JSON, or a required filter left out (for example listing status changes with none of from_date, envelope_ids, or transaction_ids). | Read the message naming the parameter, correct it, and resend. The request is not retryable as-is. |
| 401 | USER_AUTHENTICATION_FAILED | The access token is missing, invalid, or expired. Tokens expire one hour after they are issued, so a long gap between getting a token and using it triggers this. | Get a fresh access token and send it in the Authorization Bearer header. |
| 403 | USER_LACKS_PERMISSIONS | The token is valid but the user or integration does not have permission for the action, or the access token lacks the required scope. | Grant the user the needed permission, or request the missing scope, then retry. |
| 404 | ENVELOPE_DOES_NOT_EXIST | The envelope ID does not exist on this account, or the token cannot see it. The same shape applies to other missing resources, such as a template or folder. | Confirm the ID and that the account and base URI match the one the token was issued for. |
| 429 | HOURLY_APIINVOCATION_LIMIT_EXCEEDED | The account passed its hourly request quota, or a short-window burst limit. The X-RateLimit-Reset header gives the time the quota refreshes, in Unix epoch seconds. | Wait until the reset time, then resume. Spread polling out and prefer Connect webhooks over repeated status calls. |
DocuSign carries the eSignature API version in the request path, and v2.1 is the current version, an additive update over v2.0 that did not break existing calls.
The eSignature REST API v2.1 was released at DocuSign's Momentum conference in June 2019. It is an additive, backward-compatible update that did not break existing v2.0 calls: integrations could keep calling v2.0 and adopt v2.1 features at their own pace. It carries the version in the request path, so moving up is a deliberate path change rather than a silent one.
Version 2.0 was the prior eSignature REST API version. It remains callable on its own path, and DocuSign published an upgrade guide for moving from v2.0 to v2.1. Because v2.1 is additive, an integration on v2.0 was not forced to change.
An integration pins v2.1 in the path and moves up only when a new path version ships.
DocuSign eSignature API release notes ↗Bollard AI sits between a team's AI agents and DocuSign. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.