> **Source:** https://knowledge.leegality.com/document-execution/api/list-documents
> **Site:** Leegality Knowledge Base — https://knowledge.leegality.com
> **About:** Leegality is a document execution platform covering eSigning, stamps, NeSL, workflows, and REST API integration.
> **Navigation:** Every article on this site has a plain-text version at `<article-url>.txt` (this format). To get an index of all articles with their `.txt` links, read: https://knowledge.leegality.com/llms.txt
> **AI Guide:** For instructions on how to navigate this knowledge base as an AI agent, read: https://knowledge.leegality.com/ai-readable.txt

---
# GET /v3.0/sign/request/list — List documents

Search and list documents from your Leegality account with optional filters.

**Authentication:** `X-Auth-Token` header required on every request.

## Request URL

```
GET https://app1.leegality.com/api/v3.0/sign/request/list?q={q}&status={status}&max={max}&offset={offset}
```

**Environments:**
- Production: `https://app1.leegality.com/api/v3.0/sign/request/list`
- Sandbox: `https://sandbox.leegality.com/api/v3.0/sign/request/list`

---

## Parameters

| Name | In | Required | Type | Description | Example |
|------|----|----------|------|-------------|---------|
| `q` | query | No | string | Search query to find documents.  Searches across: - **Document name** — the PDF filename - **Document ID** — the unique identifier returned by the Create eSigning Request API - **Internal Reference Number (IRN)** — set during document creation  Search is **case-insensitive** and matches the **exact full value**. Partial matches are not supported — for example, searching `01KGRZ2F` will not match `01KGRZ2F9YNZ828PYDYE29JYZS`. | — |
| `status` | query | No | string | Filter documents by status. | — |
| `max` | query | No | integer | Maximum number of documents to return per page. Default: `20`. Maximum: `40`. Values above 40 are silently reset to 20.  Use with `offset` for pagination. Example: for page 2 with 10 results per page, use `max=10&offset=10`. | — |
| `offset` | query | No | integer | Number of documents to skip before returning results. Default: `0`.  Use with `max` for pagination. Example: for page 2 with 10 results per page, use `max=10&offset=10`. | — |

---

## Responses

### 200 — List of documents matching the search criteria.

Response wrapper for the List Documents API.  On success (`status: 1`), `data` contains the total count and array of matching documents.  On failure (`status: 0`), `messages` contains the error details.

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `status` | integer | No | API response status.  `1` = success, `0` = failure. Allowed: `0`, `1`. | `1` |
| `messages` | array\<Message\> | No | Array of response messages. Empty array on success.  **Error codes:** - `typeMismatch` — Invalid value for `status` parameter See **Message** below. | — |
| `data` | ListDocumentsData | No | Paginated list of documents matching the search criteria.  `total` represents the total number of matching documents across all pages, while `documents` contains only the current page of results. See **ListDocumentsData** below. | — |

#### Message

Message object containing a machine-readable code and a human-readable description. Used for success confirmations, errors, and warnings.

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `code` | string | No | Response message code. | `simpleWorkFlow.success` |
| `message` | string | No | Human-readable success or error message. | `Invitations sent successfully.` |

#### ListDocumentsData

Paginated list of documents matching the search criteria.  `total` represents the total number of matching documents across all pages, while `documents` contains only the current page of results.

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `total` | integer | No | Total number of documents matching the search/filter criteria.  Use this with `max` and `offset` to calculate pagination. | `233` |
| `documents` | array\<ListDocumentItem\> | No | Array of document summary objects for the current page. See **ListDocumentItem** below. | — |

##### ListDocumentItem

Summary of a document in the list results.

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `documentId` | string | No | Unique identifier of the document. | `01KGRZ2F9YNZ828PYDYE29JYZS` |
| `name` | string | No | Name of the document (typically the uploaded PDF filename). | `Loan-Agreement.pdf` |
| `irn` | string | No | Internal Reference Number set during document creation.  Returns `null` if no IRN was set. | `INV-2026-001` |
| `status` | string | No | Current status of the document. Allowed: `DRAFT`, `SENT`, `RECEIVED`, `SIGNED`, `COMPLETED`, `EXPIRED`. | `COMPLETED` |
| `folderId` | string | No | Unique identifier of the folder the document belongs to.  Returns `null` if not in a folder. | — |
| `folderName` | string | No | Name of the folder the document belongs to.  Returns `null` if not in a folder. | — |

### Sample Response (200)

```json
{
  "status": 1,
  "messages": [
    {
      "code": "simpleWorkFlow.success",
      "message": "Invitations sent successfully."
    }
  ],
  "data": {
    "total": 233,
    "documents": [
      {
        "documentId": "01KGRZ2F9YNZ828PYDYE29JYZS",
        "name": "Loan-Agreement.pdf",
        "irn": "INV-2026-001",
        "status": "COMPLETED",
        "folderId": "string",
        "folderName": "string"
      }
    ]
  }
}
```