> ## 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.

# Stages

> API reference for Essal Careers pipeline stages — list, create, reorder, and delete hiring stages.

## List Stages for a Pipeline

`GET /v1/careers/pipelines/{pipeline_id}/stages`

```json theme={null}
{
  "data": [
    { "id": "stg_01HXYZS1", "name": "Application Review", "order": 1 },
    { "id": "stg_01HXYZS2", "name": "Phone Screen", "order": 2 },
    { "id": "stg_01HXYZS3", "name": "Technical Interview", "order": 3 },
    { "id": "stg_01HXYZS4", "name": "Final Round", "order": 4 },
    { "id": "stg_01HXYZS5", "name": "Offer", "order": 5 }
  ]
}
```

***

## Create a Stage

`POST /v1/careers/pipelines/{pipeline_id}/stages`

```json theme={null}
{
  "name": "Take-Home Assessment",
  "order": 3
}
```

Inserting a stage at an existing `order` position shifts subsequent stages down automatically.

***

## Update a Stage

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

```json theme={null}
{ "name": "Technical Assessment", "order": 2 }
```

***

## Reorder Stages

`PUT /v1/careers/pipelines/{pipeline_id}/stages/order`

```json theme={null}
{
  "stage_ids": ["stg_01HXYZS1", "stg_01HXYZS3", "stg_01HXYZS2", "stg_01HXYZS4", "stg_01HXYZS5"]
}
```

The array order defines the new stage sequence.

***

## Delete a Stage

`DELETE /v1/careers/stages/{id}`

```json theme={null}
{ "migrate_applications_to": "stg_01HXYZS2" }
```

Specify a `migrate_applications_to` stage ID to move any candidates currently in this stage before deletion. If omitted, all candidates in the stage are disqualified.

<Warning>
  Deleting a stage with active candidates requires the `migrate_applications_to` parameter or an explicit `disqualify_candidates: true` flag. Omitting both will return a `400` error.
</Warning>