> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/guides/list-responses.md).

# List responses

This document explains how to paginate, filter, sort, and search list responses in DocStudio API.

{% hint style="info" %}
This guide focuses on mailbox envelope lists and mailbox search. Use the API reference for each endpoint's complete parameter list and response schema.
{% endhint %}

### Use pagination for mailbox envelope lists

Pagination processes a large result set in smaller pages. Request one page, process its records, and then request the next page.

Use pagination when you synchronize or process envelopes regularly. Avoid loading an entire mailbox in one request.

#### Pagination parameters

Use these query parameters where the endpoint supports them:

* `limit` — maximum records in one response
* `offset` — records to skip before returning the page

Start with a moderate page size, such as `20`, `50`, or `100`. Confirm supported limits in the endpoint reference.

#### Request the first page

```http
GET /api/v1/mailbox/{mailboxUuid}?limit=20&offset=0
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {mailboxUuid}
```

This request returns the first page with up to 20 records.

Request the next page with the same `limit` and an increased `offset`.

```http
GET /api/v1/mailbox/{mailboxUuid}?limit=20&offset=20
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {mailboxUuid}
```

### Process pages safely

Use response metadata to decide whether another page exists.

```json
{
  "totalElements": 57,
  "sizeRequested": 20,
  "numberOfElements": 20,
  "data": []
}
```

Use these values like this:

* `totalElements` — total matching records
* `sizeRequested` — page size accepted by the server
* `numberOfElements` — records in the current response
* `data` — returned records

Stop when `data` is empty or `numberOfElements` is smaller than `sizeRequested`.

Follow this flow:

1. Send the first request with `limit=20` and `offset=0`.
2. Process the returned records.
3. Send the next request with `limit=20` and `offset=20`.
4. Continue increasing `offset` by `limit`.
5. Stop when the response is empty or shorter than `sizeRequested`.

{% hint style="warning" %}
Offset pagination does not create a fixed data snapshot. New or changed envelopes can cause duplicates or skipped records. Save processed envelope UUIDs and deduplicate results during synchronization.
{% endhint %}

### Filter and sort envelope lists

Keep every filter and the sorting direction unchanged during one pagination run. Changing them can return unexpected records or skip matching envelopes.

Use `scope=inbox` for received envelopes. Use `scope=outbox` for sent envelopes.

Use `sort=desc` to process newer results first. Use `sort=asc` to process older results first.

Use specific filters when possible. The mailbox endpoint supports filters for status, archive state, sender, template, labels, subject, and date periods. It also supports `q` where text search is appropriate.

```http
GET /api/v1/mailbox/{mailboxUuid}?scope=outbox&status=COMPLETED&template={templateUuid}&archived=false&limit=50&offset=0&sort=desc
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {mailboxUuid}
```

Use this pattern to synchronize completed, unarchived envelopes from one template.

{% hint style="info" %}
Check the [Check Envelope Status](/api-reference/check-envelope-status.md) reference for supported filter values and date-period formats.
{% endhint %}

#### Encode query values

Encode spaces and special characters in query values. Use an HTTP client or URL builder that encodes parameters automatically.

```http
GET /api/v1/mailbox/{mailboxUuid}?q=Sales%20agreement&limit=20&offset=0
```

### Search mailboxes and contacts

Use mailbox search before assigning a recipient to a template role. The required `q` parameter searches mailbox UUIDs, aliases, names, and contact names.

```http
GET /api/v1/mailbox/search?q=john.doe@example.com
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {mailboxUuid}
```

Save the returned mailbox UUID and use it when you assign a recipient role.

Do not use mailbox search to check envelope status. Use the mailbox envelope endpoint for envelope lists and status checks.

### Get one envelope

Pass `UUID` when you already know the envelope UUID and need full envelope data with its template.

```http
GET /api/v1/mailbox/{mailboxUuid}?UUID={envelopeUuid}
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {mailboxUuid}
```

`mailboxUuid` identifies the target mailbox and current mailbox context. `envelopeUuid` identifies the requested envelope.

{% hint style="warning" %}
Do not use an envelope UUID where a mailbox UUID is required. Do not use mailbox search when you need an envelope.
{% endhint %}

### Synchronize envelope lists

Use this pattern for regular polling:

1. Set stable filters, sorting, `limit`, and `offset`.
2. Request one page of envelopes.
3. Process only envelope UUIDs that were not processed already.
4. Increase `offset` by `limit` and request the next page.
5. Stop when the page is empty or shorter than `sizeRequested`.
6. Retry temporary request failures with the same query parameters.

Avoid requesting very large pages unless the endpoint supports your required size.

### Troubleshoot list requests

{% columns %}
{% column %}
Check pagination and filters:

* The `limit` value is supported by the endpoint.
* The `offset` matches the requested page.
* Filters and sorting remain stable.
* Query values are URL-encoded.
* The requested status and scope are supported.
  {% endcolumn %}

{% column %}
Check identifiers and access:

* The token owner can access the mailbox.
* The path mailbox UUID is correct.
* The `mailboxUuid` header has the correct context.
* Template, label, sender, and envelope UUIDs use the correct environment.
* `UUID` is used only for one known envelope.
  {% endcolumn %}
  {% endcolumns %}

### Related topics

{% columns %}
{% column %}

* [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md)
* [Working with envelope fields](/guides/envelope-fields.md)
* [Metadata](/guides/envelope-metadata.md)
  {% endcolumn %}

{% column %}

* [Send your first envelope](/introduction/send-your-first-envelope.md)
* [Check Envelope Status](/api-reference/check-envelope-status.md)
* [Search Mailboxes and Contacts](/api-reference/search-mailboxes-and-contacts.md)
  {% endcolumn %}
  {% endcolumns %}