# List documents

{% hint style="warning" %}
This endpoint is cached by default with a TTL of 60 seconds.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api.zapsign.com.br/api/v1/docs/?page=1`

This endpoint allows you to list all documents in your account. By default, results are returned in a paginated format.

***

#### URL Parameters (Query Params)

| **Parameter**     | **Type**  | **Description**                                                                 |
| ----------------- | --------- | ------------------------------------------------------------------------------- |
| `page`            | `integer` | Page number for navigation (e.g., `?page=2`).                                   |
| `status`          | `string`  | Filter by status: `pending` (in progress), `signed`, or `refused`.              |
| `folder_path`     | `string`  | Filter documents in a specific folder. Use `/` for the root.                    |
| `deleted`         | `boolean` | `true` to list only deleted documents; `false` for active ones.                 |
| `signer_email`    | `string`  | Filter documents that contain a signer with this email.                         |
| `created_from`    | `string`  | Start date (format `YYYY-MM-DD`).                                               |
| `created_to`      | `string`  | End date (format `YYYY-MM-DD`).                                                 |
| `sort_order`      | `string`  | Sort by creation date: `asc` (oldest first) or `desc` (newest first).           |
| `include_signers` | `boolean` | (New) Use `true`, `1`, or `yes` to include the signers array for each document. |

***

#### Headers

| **Name**          | **Type** | **Description**                                                                                                           |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`\* | `string` | <p>API token preceded by the word "Bearer".</p><p><br></p><p>Ex: <code>Bearer c7f35c84-7893-4087-b4fb-d1f06c23</code></p> |

***

#### Details on the `include_signers` parameter

When this parameter is enabled, the API will return a `signers` field within each document object, containing detailed information:

* Included Fields: Name, email, phone, authentication mode (`auth_mode`), digital certificate flag, interaction timestamps, signing URL, and signing order (if order is active).
* Signer Status: Exposed via a stable enum:
  * `nao_abriu` (has not opened)
  * `abriu` (opened)
  * `assinou` (signed)
  * `recusou` (refused)
  * `expirou` (expired)
  * `cancelado` (canceled)

    *(Note: Document-level status takes precedence over individual status where applicable).*

***

#### Important Notes

* JSON Consistency: Blank strings are normalized to `null` in the API response.
* Optimized Performance: The endpoint uses `prefetch_related` to avoid N+1 query issues when requesting signers, ensuring fast responses even for large lists.
* Temporary Links: The `original_file` and `signed_file` fields return links that expire in 60 minutes.
* Caching: This endpoint has a 60-second cache. If you have just created a document, it may take up to a minute to appear in this list.

***

#### Response Examples (JSON)

**Example with `include_signers = True`**

```json
{
    "count": 120,
    "next": "https://api.zapsign.com.br/api/v1/docs/?page=2",
    "previous": null,
    "results": [
        {
            "token": "4f9e-a1b2-c3d4",
            "name": "Service Provision Contract",
            "status": "pending",
            "original_file": "https://s3.amazonaws.com/...",
            "signed_file": null,
            "created_at": "2024-03-25T14:30:00Z",
            "folder_path": "/",
            "signers": [
                {
                    "name": "João Silva",
                    "email": "joao@email.com",
                    "status": "abriu",
                    "auth_mode": "assinatura_tela",
                    "signing_url": "https://zapsign.com.br/sign/...",
                    "has_certificate": false,
                    "order": 1
                }
            ]
        }
    ]
}
```

**Example without `include_signers`**

```json
[
    {
        "open_id": 1,
        "token": "7d23fcfa-d37e-44c6-a3c1-677a66383910",
        "status": "pending",
        "name": "Test Document",
        "original_file": "https://zapsign.s3.amazonaws.com/...",
        "signed_file": null,
        "created_at": "2020-04-16T02:43:31.500058Z",
        "last_update_at": "2020-04-16T02:43:31.500122Z"
    }
]
```

***

{% hint style="info" %}
Pro Tip: Instead of polling the API multiple times a day, use our Webhooks. This saves computational capacity on both our servers and yours, and allows you to provide real-time feedback to your users.
{% endhint %}

{% hint style="warning" %}
Attention: Links returned in `original_file` and `signed_file` are temporary and last 60 minutes. If your system needs to store these links, we recommend downloading them to your own CDN or querying this endpoint whenever a fresh link is needed.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zapsign.com.br/english/documentos/listar-documentos.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.