> 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

# Agreement Desk API concepts

> Learn about important concepts and objects used by the Agreement Desk API.

The following sections describe the objects and key terms used by the Agreement Desk API.

## Agreements

An agreement is a commitment between two or more parties that creates an obligation to perform (or not perform) a particular duty. Typically, agreements will contain a lot of other data, such as documents that describe the agreement being struck, parties who are involved in the agreement, dates defining the boundaries of the agreement, and many more.

## Agreement requests

An agreement request is a trackable record for the process for creating an agreement. It provides a central place to manage intake information, participants, documents, status, approvals, discussion, and related activity.

Agreement requests are scoped to a Docusign account. A request is created under an account and is identified by a request ID and request URL.

An agreement request will contain information on many related objects, including intake forms, users and participants, status, documents, approvals, message records, permissions, and envelopes.

## Request type

A request type (also called an intake form) defines the data contract for a specific kind of agreement request . You could define individual request types for NDA requests, supplier agreements, contract renewals, or customer agreement requests, for example.

In the Agreement Desk API, `requestTypeId` identifies an Agreement Desk intake form or request type. It is not an eSignature template ID or a document-generation template ID.

To find an intake form, list the active forms in the target account:

`GET /v1/accounts/{accountId}/request-types`

You can then use the id returned for the selected form as `requestTypeId` when creating a request; the form must exist in the account and its status must be active.

## Users and Participants

Users and participants are people associated with an agreement request. Common relationships include:

* **Submitter**: The person who initiated the request. If `submitter_id` is omitted, the authenticated caller is used in the current create-request behavior.
* **Owner**: The person responsible for managing the request. An owner can be assigned explicitly or by a workflow.
* **Approver**: A person who makes a decision at an approval gate.
* **Follower**: A person who receives request updates or has request visibility.
* **Collaborator**: A participant who contributes to the request without necessarily owning or approving it.

The `owner_id` and `submitter_id` refer to Docusign user or participant user IDs. Explicitly setting these fields is permission-sensitive, and the referenced users must be valid members of the target account.

## Request Statuses

A request status represents the current lifecycle state of an agreement request. Statuses are configured by the account, so status names and transitions can differ between accounts.

A status object can include properties such as:

* Status ID.
* Display name.
* Open or closed state.
* Display color.
* Sort order.

Integrations should not hard-code status names such as New, Legal Review, or Ready for Signature. Instead, discover the account’s statuses and use status identifiers or account-specific configuration when synchronizing lifecycle state.

A status change can be used to trigger downstream synchronization or workflow actions.

## Documents

A document contains the content associated with an agreement request, typically outlining the details of the agreement itself, later signed by participants via an eSignature flow. Documents can be uploaded, generated, retrieved, labeled, and selected for signing or downstream storage.

Documents have their own identifiers and should not be confused with the request ID or `request-type`  ID. A document-generation template ID, when used, is a separate identifier from `requestTypeId`.

## Approvals

An Approval represents a decision gate associated with an agreement request. Approval data can include the approval ID, approvers, status, creation time, due date, decision, and rejection reason.

Approvals are distinct from request ownership and followers. A request owner may coordinate the work without being an approver, and a follower may receive updates without having approval authority.

## Messages and Activity

Messages support collaboration around a request. Activity provides an operational history of request changes and related events.

Messages are typically used to:

* Synchronize request updates back to a CRM or procurement system.
* Maintain a secure record of all changes to an agreement.
* Explain why a request changed status or ownership.
* Support retry and reconciliation processing.

## Permissions and Sharing

Permissions determine what a participant can do with a request. For example, a caller may be able to create a request but lack the permission required to assign it to a different owner or submitter.

A participant must be a member of your account in order to share an agreement request with them.

The different levels of permissions available in the Agreement Desk API are:

| Permission | Typical capabilities                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| **VIEW**   | View request details, documents, messages, approvals, and share-related information.                    |
| **EDIT**   | View capabilities plus edit intake/form data, upload documents, and add messages.                       |
| **MANAGE** | Edit capabilities plus update request information, change status, manage approvals, and send envelopes. |
| **REMOVE** | Revoke the user’s access; this is an access-removal operation rather than a normal grant level.         |

**Note:** Integrations should handle 403 Forbidden responses explicitly and should not assume that a valid user ID is sufficient for every operation.

## Envelopes

An envelope is the eSignature transaction used to send an approved agreement for signing. It contains the documents, sender, recipients, signing information, and envelope status.

## Next steps

* Learn about [Agreement Desk API use cases](/docs/agreement-desk-api/use-cases)
* See the overview of Agreement Desk API and learn about where and how to use it in [Agreement Desk API 101](/docs/agreement-desk-api/agreement-desk-api-101)