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

# Applications

> API reference for Essal Careers applications — list, retrieve, advance stages, disqualify, and attach files.

## List Applications

`GET /v1/careers/jobs/{job_id}/applications`

**Query Parameters**

| Parameter  | Type   | Description                           |
| ---------- | ------ | ------------------------------------- |
| `status`   | enum   | `active`, `disqualified`, `withdrawn` |
| `stage_id` | string | Filter by current hiring stage        |
| `sort`     | string | e.g. `submitted_at:asc`, `score:desc` |

***

## Get an Application

`GET /v1/careers/applications/{id}`

Returns the full application including candidate info, stage history, scorecard average, and attached files.

***

## Submit an Application (Public)

`POST /v1/careers/jobs/{job_id}/applications`

This endpoint is unauthenticated and used by the public careers site form:

```json theme={null}
{
  "candidate": {
    "display_name": "Alice Johnson",
    "email": "alice.j@example.com",
    "phone": "+44 7700 900456"
  },
  "answers": [
    { "field": "cover_letter", "value": "I am excited to apply for this role..." }
  ]
}
```

***

## Advance Stage

`PATCH /v1/careers/applications/{id}`

```json theme={null}
{
  "stage_id": "stg_01HXYZS3",
  "stage_note": "Strong phone screen. Moving to technical round."
}
```

***

## Disqualify an Applicant

`POST /v1/careers/applications/{id}/disqualify`

```json theme={null}
{
  "reason": "insufficient_experience",
  "notify_candidate": true
}
```

***

## Attach a File to an Application

`POST /v1/careers/applications/{id}/attachments`

```json theme={null}
{ "file_id": "fil_01HXYZFIL9", "label": "Portfolio" }
```