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

# Assessment flows

> Partner API for multi-step assessment flows (sequences of quizzes and interviews)

Assessment flows group ordered steps (each step is an existing assessment). Use this API to list flows, create or update them, inspect a flow with step metadata, list candidates assigned to a flow, and assign a candidate (which creates the assignment and sends the first-step invite email).

**Base path:** `/v1/partner/assessment-flows`\
**Authentication:** `Authorization: Bearer YOUR_API_KEY`

Related: single assessments are managed under [Assessments](/api-reference/assessments). Workspace users and teams are under [Users](/api-reference/users) and [Teams](/api-reference/teams).

***

## List flows

### `GET /assessment-flows`

Returns all non-deleted flows for the API key’s workspace, including steps and candidate counts where available.

### Example request

```bash theme={null}
curl -X GET "https://partner-api.taptalent.io/v1/partner/assessment-flows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Example response

```json theme={null}
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "companyId": "company-uuid",
      "flowName": "Engineering screen",
      "description": null,
      "status": "ACTIVE",
      "candidateCount": 3,
      "steps": []
    }
  ]
}
```

***

## Create flow

### `POST /assessment-flows`

**Body (JSON):**

| Field         | Type   | Required | Description          |
| ------------- | ------ | -------- | -------------------- |
| `flowName`    | string | Yes      | Name of the flow     |
| `description` | string | No       | Optional description |
| `steps`       | array  | Yes      | At least one step    |

**Each step:**

| Field                                | Type   | Required | Description                                     |
| ------------------------------------ | ------ | -------- | ----------------------------------------------- |
| `assessmentId`                       | string | Yes      | Existing assessment (test) id                   |
| `passThreshold`                      | number | Yes      | 0–100                                           |
| `assessmentType` / `type`            | string | No       | If omitted, resolved from the assessment record |
| `name`, `instructions`, `passAction` | string | No       | Optional step metadata                          |

### Example request

```bash theme={null}
curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment-flows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flowName": "Engineering screen",
    "description": "Quiz then interview",
    "steps": [
      {
        "assessmentId": "test-uuid-1",
        "passThreshold": 60,
        "name": "Technical quiz"
      },
      {
        "assessmentId": "test-uuid-2",
        "passThreshold": 70
      }
    ]
  }'
```

### Example response

```json theme={null}
{
  "status": "success",
  "data": {
    "id": 10,
    "flowName": "Engineering screen",
    "companyId": "company-uuid",
    "status": "ACTIVE"
  }
}
```

***

## Update flow

### `PATCH /assessment-flows/:id`

Updates name, description, status, and steps. The underlying service restricts changing or removing existing stages; you may adjust thresholds and append new stages (same rules as the in-app flow editor).

**Body:** Same shape as create (`flowName`, optional `description`, optional `status`, `steps`).

***

## Get flow details

### `GET /assessment-flows/:id`

Returns the flow with steps, including `assessmentName` and `assessmentDuration` enriched from assessment records.

### Path parameters

| Parameter | Description |
| --------- | ----------- |
| `id`      | Flow id     |

If the flow does not belong to the workspace, the API returns **404**.

***

## List flow candidates

### `GET /assessment-flows/:id/candidates`

Paginated list of candidates assigned to the flow, with attempts and submission metadata when available.

### Query parameters

| Parameter               | Type    | Description                                                 |
| ----------------------- | ------- | ----------------------------------------------------------- |
| `page`                  | integer | Page number (default 1)                                     |
| `pageSize` or `perPage` | integer | Page size (default 10, max 100)                             |
| `search`                | string  | Substring match on candidate name or email                  |
| `status`                | string  | One of: `NOT_STARTED`, `IN_PROGRESS`, `COMPLETED`, `FAILED` |

### Example response

```json theme={null}
{
  "status": "success",
  "data": [],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 0
  }
}
```

***

## Assign candidate

### `POST /assessment-flows/:id/assign`

Creates a flow assignment and sends the **first step** assessment invite email (same behavior as the client app). Either provide `email` (and optional `firstName` / `lastName`) or `jobCandidateId` so the server can resolve the candidate.

**Body (JSON):**

| Field                   | Type          | Required | Description                                             |
| ----------------------- | ------------- | -------- | ------------------------------------------------------- |
| `email`                 | string        | Yes\*    | Candidate email (\*unless `jobCandidateId` is provided) |
| `firstName`, `lastName` | string        | No       | Used when inviting by email                             |
| `jobCandidateId`        | number/string | No       | Job candidate id                                        |
| `jobId`                 | number/string | No       | Optional job context                                    |
| `talentId`              | number/string | No       | Optional                                                |

### Example response

```json theme={null}
{
  "status": "success",
  "data": {
    "message": "Flow assigned successfully",
    "flowCandidateId": 42,
    "firstStepAssessmentId": "test-uuid-1"
  }
}
```

***

## Errors

Validation errors return **400** with `code: "INVALID_REQUEST"`. Missing or cross-workspace flows return **404** with `code: "NOT_FOUND"`. Other failures may return **403** or **500** with an `error` object; see [API Reference Overview](/api-reference/overview).

***

## Related

* [Assessments](/api-reference/assessments) — Create and invite for individual assessments
* [API Reference Overview](/api-reference/overview) — Base URL and authentication