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

# List Applications (v2)

> Enhanced application listing with advanced filtering by OG variables

## List Applications (v2)

Retrieve a paginated list of applications with advanced filtering capabilities including OG variable filters.

### Endpoint

```
POST /external/v2/applications/
```

### Authentication

> \[!NOTE]
> Requires a valid company API key in the `Authorization` header (format: `Api-Key <key>`).

### Request Body

| Field             | Type              | Required | Description                                     |
| ----------------- | ----------------- | -------- | ----------------------------------------------- |
| `flow_id`         | string (UUID)     | Yes      | The flow ID (must belong to the company)        |
| `current_stage`   | string (UUID)     | No       | Filter by stage ID                              |
| `application_ids` | array of strings  | No       | Optional list of application IDs to include     |
| `og_variable_ids` | array of strings  | No       | Optional list of OG variable paths to return    |
| `filters`         | object            | No       | Dict of `{og_path: value}` pairs for filtering  |
| `page`            | integer           | No       | Page number (1-based)                           |
| `page_size`       | integer           | No       | Items per page                                  |
| `created__gt`     | string (ISO 8601) | No       | Applications created after this datetime        |
| `created__gte`    | string (ISO 8601) | No       | Applications created on or after this datetime  |
| `created__lt`     | string (ISO 8601) | No       | Applications created before this datetime       |
| `created__lte`    | string (ISO 8601) | No       | Applications created on or before this datetime |
| `updated_at__gt`  | string (ISO 8601) | No       | Applications updated after this datetime        |
| `updated_at__gte` | string (ISO 8601) | No       | Applications updated on or after this datetime  |
| `updated_at__lt`  | string (ISO 8601) | No       | Applications updated before this datetime       |
| `updated_at__lte` | string (ISO 8601) | No       | Applications updated on or before this datetime |

### Filter Value Formats

The `filters` field supports different value formats depending on the field type:

| Field Type           | Format                                                                                        | Example                                     |
| -------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------- |
| Text / Email / Phone | Plain string (case-insensitive substring)                                                     | `"john"`                                    |
| Selection            | Comma-separated choice IDs, or `{"values_to_include": ["id1"], "check_for_empty": true}`      | `"choice-id-1,choice-id-2"`                 |
| Date                 | Named preset (`TODAY`, `THIS_WEEK`, `THIS_MONTH`, `THIS_YEAR`) or range `"startDate,endDate"` | `"2024-01-01,2024-12-31"`                   |
| Number               | Range `"min,max"` (use `"null"` for open-ended)                                               | `"50,100"` or `"50,null"`                   |
| Document             | Boolean                                                                                       | `true` (uploaded) or `false` (not uploaded) |

### Example Request

```bash theme={null}
curl -X POST "https://api.firstwork.com/external/v2/applications/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "550e8400-e29b-41d4-a716-446655440000",
    "og_variable_ids": [
      "USER.PERSONAL_INFORMATION.first_name",
      "USER.PERSONAL_INFORMATION.last_name"
    ],
    "filters": {
      "USER.PERSONAL_INFORMATION.first_name": "John"
    },
    "page": 1,
    "page_size": 50
  }'
```

### Response Structure

Returns a paginated envelope with:

* `results`: Array of application records with dynamic keys per requested variables
* `labels_map`: Mapping of variable keys to human-readable labels
* `unavailable_application_ids`: IDs that were requested but not found
* `errored_request_variables`: Invalid variable IDs

### Responses

#### 200: OK

Paginated list of applications' attributes (dynamic keys).

#### 400: Bad Request

Missing/invalid parameters, invalid datetime format, or unrecognised filter paths.

#### 500: Internal Server Error

Unexpected error.