> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Requests

> Previous version of List Forms. Retrieve a list of requests with filtering.

<Warning>
  Previous API version. Use [`GET /forms`](/api-reference/requests/list-requests) for new integrations. This route still works but is deprecated.
</Warning>

Retrieve a list of requests (now called forms) matching specific criteria.

```text theme={null}
GET https://connect.penbox.io/v1/requests
```

## Query Parameters

| Parameter      | Type   | Description                                                                      |
| -------------- | ------ | -------------------------------------------------------------------------------- |
| `filter`       | string | JSON-encoded filter object (workspace, flow, user, owner, status, external args) |
| `page[number]` | number | Page number (starts at 1)                                                        |
| `page[size]`   | number | Results per page (default: 10, max: 100)                                         |

The `filter` object accepts the same keys as the current endpoint: `company.slug`, `flow.slug`, `user`, `owner.email`, `active`, `archived`, `completed`, `processed`, and `external_args`. See the [Advanced Filters guide](/api-reference/advanced-filters).

## Response

<Warning>
  Unlike the current `GET /forms` endpoint, this route returns a **bare JSON array** with no pagination `meta` envelope.
</Warning>

```json theme={null}
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2024-01-15T10:30:00Z",
    "status": "pending",
    "archived": false,
    "user": {
      "email": "client@example.com",
      "given_name": "John",
      "family_name": "Doe"
    },
    "external_args": { "crm_id": "12345" },
    "flow": { "slug": "client-onboarding" },
    "owner": null,
    "active_from": "2024-01-15T10:30:00Z",
    "active_until": null,
    "archived_at": null,
    "processed_at": null,
    "workspace": { "id": "...", "slug": "acme-corp" },
    "links": { "fill": "https://...", "app": "https://..." },
    "responses": []
  }
]
```

## Example

```bash cURL theme={null}
curl 'https://connect.penbox.io/v1/requests' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

## Response Codes

| Code  | Description                                    |
| ----- | ---------------------------------------------- |
| `200` | Success — returns array of requests            |
| `400` | Bad Request — invalid filter parameters        |
| `401` | Unauthorized — invalid or expired access token |
| `403` | Forbidden — token lacks required permissions   |
| `429` | Too Many Requests — rate limit exceeded        |
| `500` | Server Error                                   |