Skip to navigation
Agreement Desk API 101

Agreement Desk API concepts

View as Markdown

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:

PermissionTypical capabilities
VIEWView request details, documents, messages, approvals, and share-related information.
EDITView capabilities plus edit intake/form data, upload documents, and add messages.
MANAGEEdit capabilities plus update request information, change status, manage approvals, and send envelopes.
REMOVERevoke 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