> 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

# List requests

GET https://api-d.docusign.com/v1/accounts/{accountId}/requests

Returns a paginated list of requests for the account, optionally filtered by status state.

Reference: https://developers.docusign.com/docs/agreement-desk-api/reference/agreementdesk/requests/listrequests

## Authentication

- `Authorization` header (bearer token, required) — Docusign OAuth 2.0 access token

## Servers

- `https://api-d.docusign.com` (Demo, default)
- `https://api.docusign.com` (Production)

## Request

### Path parameters

- `accountId` (string, required) — The ID of the account that owns the request statuses.

### Query parameters

- `limit` (integer, optional, default: 25) — The maximum number of items to return in a single page.
- `ctoken` (string, optional) — The continuation token identifying the page of results to return. Obtained from the `next` hypermedia link of a previous response; omit to retrieve the first page.
- `state` (enum, optional) — Filters requests by the lifecycle state of their status. Omit to return both open and closed requests.
  - Allowed values: `Open`, `Closed`

## Response

### 200

The paginated list of requests for the account.

- `_links` (PageLinks, optional) — Hypermedia controls (HATEOAS) for navigating between pages in a paginated collection of results. Links for the current page, next page, and previous page.
- `response_metadata` (ResponseMetadata, optional) — Control information and metadata for the response.
- `requests` (list of RequestSummary, optional) — The requests for the account.

## Errors

### 400 Bad Request Error

The request was malformed.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

### 401 Unauthorized Error

The request was not authenticated.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

### 403 Forbidden Error

The caller is not permitted to list requests.

- `status` (integer, required) — The HTTP status code generated for this occurrence of the problem.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `type` (string, required) — A URI reference that identifies the problem type.
- `detail` (string, optional) — A human-readable explanation specific to this occurrence of the problem.
- `errors` (list of ValidationError, optional) — Field-level validation errors when multiple issues exist.
- `instance` (string, optional) — A URI reference that identifies the specific occurrence of the problem.
- `request_id` (string, optional) — Unique identifier for the request, useful for tracing with support.
- `timestamp` (datetime, optional) — The timestamp when the error occurred.

## Types

### PageLinks

Hypermedia controls (HATEOAS) for navigating between pages in a paginated collection of results. Links for the current page, next page, and previous page.

- `collection` (PageLink, optional) — A URL that references a specific page in the pagination process.
- `next` (PageLink, optional) — A URL that references a specific page in the pagination process.
- `self` (PageLink, optional) — A URL that references a specific page in the pagination process.

### ResponseMetadata

Control information and metadata for the response.

- `request_id` (string, required, nullable) — Unique identifier for the request, useful for tracking and debugging.
- `response_timestamp` (datetime, required, nullable) — The timestamp indicating when the response was generated.
- `page_limit` (integer, optional, nullable, default: 25) — The maximum number of items that can be returned in a single page.

### RequestSummary

A summary view of a request, as returned in list results.

- `_links` (PageLinks, optional) — Hypermedia controls (HATEOAS) for navigating between pages in a paginated collection of results. Links for the current page, next page, and previous page.
- `metadata` (ResourceMetadata, optional) — Audit and provenance metadata for a resource.
- `id` (string, optional) — The unique identifier of the request.
- `title` (string, optional) — The title of the request.
- `friendly_id` (string, optional, nullable) — A human-readable identifier for the request (e.g. REQ-0042).
- `status` (RequestStatus, optional)
- `intake_form_id` (string, optional) — The identifier of the intake form the request was created from.
- `request_type_name` (string, optional, nullable) — The display name of the request type.
- `owner` (ParticipantSummary, optional) — A concise reference to a participant, such as the creator of a resource.
- `submitter` (ParticipantSummary, optional) — A concise reference to a participant, such as the creator of a resource.
- `due_date` (date, optional, nullable) — The date the request is due.
- `document_count` (integer, optional) — The number of documents attached to the request.
- `approval_count` (integer, optional) — The number of approvals on the request.
- `last_activity_at` (datetime, optional, nullable) — Timestamp of the most recent activity on the request.

### ValidationError

A single field-level or parameter-level validation error.

- `code` (string, required) — A machine-readable error code identifying the specific validation failure.
- `message` (string, required) — A human-readable description of the validation error.
- `target` (string, optional) — The name of the field, parameter, or path segment that caused the error.

### PageLink

A URL that references a specific page in the pagination process.

- `href` (string, required) — The URL for the referenced page.

### ResourceMetadata

Audit and provenance metadata for a resource.

- `created_at` (datetime, optional, nullable) — Timestamp when the resource was created.
- `created_by` (string, optional, nullable) — User ID of the person who created the resource.
- `modified_at` (datetime, optional, nullable) — Timestamp when the resource was last modified.
- `modified_by` (string, optional, nullable) — User ID of the person who last modified the resource.

### RequestStatus

- `id` (string, optional)
- `name` (string, optional)
- `state` (string, optional)
- `metadata` (ResourceMetadata, optional) — Audit and provenance metadata for a resource.

### ParticipantSummary

A concise reference to a participant, such as the creator of a resource.

- `participant_id` (string, required) — The unique identifier of the participant.
- `email` (string, optional, nullable) — The email address of the participant.
- `name` (string, optional, nullable) — The display name of the participant.

## Examples

**Response**

```json
{
  "_links": {
    "collection": {
      "href": "https://api.docusign.com/v1/accounts/12345678/request-statuses?limit=10&ctoken=abc123"
    },
    "next": {
      "href": "https://api.docusign.com/v1/accounts/12345678/request-statuses?limit=10&ctoken=abc123"
    },
    "self": {
      "href": "https://api.docusign.com/v1/accounts/12345678/request-statuses?limit=10&ctoken=abc123"
    }
  },
  "response_metadata": {
    "request_id": "3f7c9e4b-851c-4f9b-89e7-123456789abc",
    "response_timestamp": "2024-10-17T14:30:00Z",
    "page_limit": 10
  },
  "requests": [
    {
      "_links": {
        "collection": {
          "href": "https://api.docusign.com/v1/accounts/12345678/request-statuses?limit=10&ctoken=abc123"
        },
        "next": {
          "href": "https://api.docusign.com/v1/accounts/12345678/request-statuses?limit=10&ctoken=abc123"
        },
        "self": {
          "href": "https://api.docusign.com/v1/accounts/12345678/request-statuses?limit=10&ctoken=abc123"
        }
      },
      "metadata": {
        "created_at": "2024-01-15T09:30:00Z",
        "created_by": "string",
        "modified_at": "2024-01-15T09:30:00Z",
        "modified_by": "string"
      },
      "id": "string",
      "title": "string",
      "friendly_id": "string",
      "status": {
        "id": "string",
        "name": "string",
        "state": "string",
        "metadata": {
          "created_at": "2024-01-15T09:30:00Z",
          "created_by": "string",
          "modified_at": "2024-01-15T09:30:00Z",
          "modified_by": "string"
        }
      },
      "intake_form_id": "string",
      "request_type_name": "string",
      "owner": {
        "participant_id": "string",
        "email": "string",
        "name": "string"
      },
      "submitter": {
        "participant_id": "string",
        "email": "string",
        "name": "string"
      },
      "due_date": "2023-01-15",
      "document_count": 1,
      "approval_count": 1,
      "last_activity_at": "2024-01-15T09:30:00Z"
    }
  ]
}
```