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

# Job Pipelines

> API endpoints for managing job pipelines and their stages

The Job Pipelines API allows you to create, update, and retrieve job pipelines for your company. Pipelines define the stages through which candidates progress in your hiring process.

## Get All Pipelines

Retrieve all pipelines for your company.

### `GET /pipelines`

### Authentication

Requires API key authentication via `Authorization: Bearer YOUR_API_KEY` header.

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/pipelines" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": [
    {
      "id": 123,
      "name": "Engineering Pipeline",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z",
      "stages": [
        {
          "id": 789,
          "name": "Sourced",
          "type": "SOURCED",
          "createdAt": "2024-01-15T10:00:00.000Z",
          "updatedAt": "2024-01-15T10:00:00.000Z"
        },
        {
          "id": 790,
          "name": "Applied",
          "type": "APPLIED",
          "createdAt": "2024-01-15T10:00:00.000Z",
          "updatedAt": "2024-01-15T10:00:00.000Z"
        },
        {
          "id": 791,
          "name": "Phone Screen",
          "type": "SCREEN",
          "createdAt": "2024-01-15T10:00:00.000Z",
          "updatedAt": "2024-01-15T10:00:00.000Z"
        }
      ]
    },
    {
      "id": 124,
      "name": "Sales Pipeline",
      "createdAt": "2024-01-16T10:00:00.000Z",
      "updatedAt": "2024-01-16T10:00:00.000Z",
      "stages": [
        {
          "id": 792,
          "name": "Sourced",
          "type": "SOURCED",
          "createdAt": "2024-01-16T10:00:00.000Z",
          "updatedAt": "2024-01-16T10:00:00.000Z"
        }
      ]
    }
  ]
}
```

## Get Pipeline Details

Retrieve a specific pipeline with all its stages.

### `GET /pipelines/:pipelineId`

### Authentication

Requires API key authentication via `Authorization: Bearer YOUR_API_KEY` header.

### Path Parameters

| Parameter    | Type    | Description                           |
| ------------ | ------- | ------------------------------------- |
| `pipelineId` | integer | The unique identifier of the pipeline |

### Example Request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/pipelines/123" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv"
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
        "id": 123,
        "name": "Engineering Pipeline",
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-01-15T10:00:00.000Z",
        "stages": [
          {
            "id": 789,
            "name": "Sourced",
            "type": "SOURCED",
            "createdAt": "2024-01-15T10:00:00.000Z",
            "updatedAt": "2024-01-15T10:00:00.000Z"
          },
          {
            "id": 790,
            "name": "Applied",
            "type": "APPLIED",
            "createdAt": "2024-01-15T10:00:00.000Z",
            "updatedAt": "2024-01-15T10:00:00.000Z"
          },
          {
            "id": 791,
            "name": "Phone Screen",
            "type": "SCREEN",
            "createdAt": "2024-01-15T10:00:00.000Z",
            "updatedAt": "2024-01-15T10:00:00.000Z"
          }
        ]
  }
}
```

### Error Responses

**Pipeline not found**:

```json theme={null}
{
  "error": {
    "code": "PIPELINE_NOT_FOUND",
    "type": "resource_error",
    "message": "Pipeline not found"
  }
}
```

**Unauthorized access**:

```json theme={null}
{
  "error": {
    "code": "PERMISSION_DENIED",
    "type": "authorization_error",
    "message": "You are not authorized to access this pipeline"
  }
}
```

## Create Pipeline

Create a new job pipeline for your company. A new pipeline will automatically include default stages: `SOURCED`, `APPLIED`, `ASSESSMENT`, `SCREEN`, `SHORTLISTED`, and `HIRED`. See [Valid Stage Types](#valid-stage-types) for details.

### `POST /pipelines`

### Authentication

Requires API key authentication via `Authorization: Bearer YOUR_API_KEY` header.

### Request Body

| Field  | Type   | Required | Description                                      |
| ------ | ------ | -------- | ------------------------------------------------ |
| `name` | string | Yes      | Pipeline name (must be non-empty after trimming) |

### Request Body Example

```json theme={null}
{
  "name": "Engineering Pipeline"
}
```

### Example Request

```bash theme={null}
curl -X POST "https://partner-api.taptalent.io/v1/partner/pipelines" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Pipeline"
  }'
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Engineering Pipeline"
  }
}
```

### Error Responses

**Missing pipeline name**:

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Pipeline name is required"
  }
}
```

## Update Pipeline

Update the name of an existing pipeline.

### `PUT /pipelines/:pipelineId`

### Authentication

Requires API key authentication via `Authorization: Bearer YOUR_API_KEY` header.

### Path Parameters

| Parameter    | Type    | Description                                     |
| ------------ | ------- | ----------------------------------------------- |
| `pipelineId` | integer | The unique identifier of the pipeline to update |

### Request Body

| Field  | Type   | Required | Description                                          |
| ------ | ------ | -------- | ---------------------------------------------------- |
| `name` | string | Yes      | New pipeline name (must be non-empty after trimming) |

### Request Body Example

```json theme={null}
{
  "name": "Updated Engineering Pipeline"
}
```

### Example Request

```bash theme={null}
curl -X PUT "https://partner-api.taptalent.io/v1/partner/pipelines/123" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Engineering Pipeline"
  }'
```

### Example Response

```json theme={null}
{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Updated Engineering Pipeline"
  }
}
```

### Error Responses

**Pipeline not found**:

```json theme={null}
{
  "error": {
    "code": "PIPELINE_NOT_FOUND",
    "type": "resource_error",
    "message": "Pipeline not found"
  }
}
```

**Unauthorized access**:

```json theme={null}
{
  "error": {
    "code": "PERMISSION_DENIED",
    "type": "authorization_error",
    "message": "You are not authorized to update this pipeline"
  }
}
```

**Missing pipeline name**:

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Pipeline name is required"
  }
}
```

## Create or Update Pipeline Stage

Create a new stage or update an existing stage in a pipeline. When updating, you can optionally change the stage's order, which will automatically adjust the order of other stages.

### `POST /pipelines/stages`

### Authentication

Requires API key authentication via `Authorization: Bearer YOUR_API_KEY` header.

### Request Body

| Field        | Type    | Required | Description                                                                                                                                             |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pipelineId` | integer | Yes      | The unique identifier of the pipeline                                                                                                                   |
| `name`       | string  | Yes      | Stage name (required for new stages, optional for updates)                                                                                              |
| `type`       | string  | Yes      | Stage type (required for new stages, optional for updates). Valid types: `ASSESSMENT`, `SCREEN`, `SHORTLISTED`, `OFFER`, `ONBOARDING`                   |
| `stageId`    | integer | No       | Stage ID (if provided, updates existing stage; if omitted, creates new stage)                                                                           |
| `order`      | integer | No       | Desired order position (1-based). If not provided, new stages are placed before HIRED stage. When updating, adjusts other stages' orders automatically. |

### Request Body Examples

**Create a new stage:**

```json theme={null}
{
  "pipelineId": 123,
  "name": "Technical Interview",
  "type": "SCREEN",
  "order": 3
}
```

**Update an existing stage:**

```json theme={null}
{
  "pipelineId": 123,
  "stageId": 791,
  "name": "Updated Stage Name",
  "type": "ASSESSMENT",
  "order": 2
}
```

**Update only the name of a non-editable stage (SOURCED, APPLIED, HIRED):**

```json theme={null}
{
  "pipelineId": 123,
  "stageId": 789,
  "name": "Updated Sourced Stage Name"
}
```

### Example Request

```bash theme={null}
curl -X POST "https://partner-api.taptalent.io/v1/partner/pipelines/stages" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId": 123,
    "name": "Technical Interview",
    "type": "SCREEN",
    "order": 3
  }'
```

### Example Response

**Create response (201):**

```json theme={null}
{
  "status": "success",
  "data": {
    "id": 791,
    "name": "Technical Interview",
    "type": "SCREEN",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:00:00.000Z"
  }
}
```

**Update response (200):**

```json theme={null}
{
  "status": "success",
  "data": {
    "id": 791,
    "name": "Updated Stage Name",
    "type": "ASSESSMENT",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T11:00:00.000Z"
  }
}
```

### Error Responses

**Invalid stage type:**

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Stage type is not valid"
  }
}
```

**Invalid order range:**

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Order must be between 1 and 5"
  }
}
```

**Invalid stage ID:**

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Stage ID is not valid"
  }
}
```

## Delete Pipeline Stage

Delete a stage from a pipeline. All candidates in the deleted stage will be moved to the specified new stage. The remaining stages will be automatically reordered.

### `DELETE /pipelines/stages/:stageId`

### Authentication

Requires API key authentication via `Authorization: Bearer YOUR_API_KEY` header.

### Path Parameters

| Parameter | Type    | Description                                  |
| --------- | ------- | -------------------------------------------- |
| `stageId` | integer | The unique identifier of the stage to delete |

### Request Body

| Field        | Type    | Required | Description                                                          |
| ------------ | ------- | -------- | -------------------------------------------------------------------- |
| `pipelineId` | integer | Yes      | The unique identifier of the pipeline                                |
| `newStageId` | integer | Yes      | The stage ID where candidates from the deleted stage should be moved |

### Request Body Example

```json theme={null}
{
  "pipelineId": 123,
  "newStageId": 790
}
```

### Example Request

```bash theme={null}
curl -X DELETE "https://partner-api.taptalent.io/v1/partner/pipelines/stages/791" \
  -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUv" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId": 123,
    "newStageId": 790
  }'
```

### Example Response

```json theme={null}
{
  "status": "success",
  "message": "Stage deleted successfully"
}
```

### Error Responses

**Cannot delete system stages:**

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Cannot delete SOURCED, APPLIED, or HIRED stages"
  }
}
```

**Invalid stage ID:**

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "type": "validation_error",
    "message": "Stage ID is invalid"
  }
}
```

## Valid Stage Types

When creating or updating pipeline stages, you must use one of the following valid stage types:

| Stage Type    | Description                                          | Default | Editable       | Deletable |
| ------------- | ---------------------------------------------------- | ------- | -------------- | --------- |
| `SOURCED`     | Candidates who have been sourced but haven't applied | Yes     | No (name only) | No        |
| `APPLIED`     | Candidates who have applied to the job               | Yes     | No (name only) | No        |
| `ASSESSMENT`  | Candidates in assessment/interview stage             | Yes     | Yes            | Yes       |
| `SCREEN`      | Candidates in screening stage                        | Yes     | Yes            | Yes       |
| `SHORTLISTED` | Candidates who have been shortlisted                 | Yes     | Yes            | Yes       |
| `OFFER`       | Candidates who have received an offer                | No      | Yes            | Yes       |
| `ONBOARDING`  | Candidates in onboarding process                     | No      | Yes            | Yes       |
| `HIRED`       | Candidates who have been hired                       | Yes     | No (name only) | No        |

**Important Notes:**

* **Default Stages**: When you create a new pipeline, it automatically includes these default stages: `SOURCED`, `APPLIED`, `ASSESSMENT`, `SCREEN`, `SHORTLISTED`, and `HIRED`.
* **System Stages** (`SOURCED`, `APPLIED`, `HIRED`): These stages cannot be deleted or have their type changed. Only the name can be updated.
* **Custom Stages** (`ASSESSMENT`, `SCREEN`, `SHORTLISTED`, `OFFER`, `ONBOARDING`): These stages can be created, updated (including type), and deleted.
* **Stage Type Validation**: When creating a new stage, the `type` field must be one of the valid types listed above. Invalid types will result in a validation error.

## Notes

* **Pipeline Ownership**: All pipelines belong to a company. You can only access and modify pipelines that belong to your company.

* **Stage Ordering**:
  * Stages have an order (1-based) that determines their position in the pipeline
  * When creating a new stage, you can specify an `order` to place it at a specific position. If not specified, it will be placed before the HIRED stage
  * When updating a stage's order, other stages will automatically be adjusted to maintain sequential ordering
  * The `SOURCED` stage order is locked and cannot be changed

* **Stage Deletion**:
  * When deleting a stage, all candidates in that stage must be moved to another stage (specified by `newStageId`)
  * System stages (`SOURCED`, `APPLIED`, `HIRED`) cannot be deleted
  * After deletion, remaining stages are automatically reordered sequentially