Assessment flows

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. Workspace users and teams are under Users and 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

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

{
  "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

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

{
  "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

{
  "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

{
  "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.

Assessments — Create and invite for individual assessments
API Reference Overview — Base URL and authentication

Get Started

Authentication

API Reference

Webhooks

Integration Notes

List flows

`GET /assessment-flows`

Example request

Example response

Create flow

`POST /assessment-flows`

Example request

Example response

Update flow

`PATCH /assessment-flows/:id`

Get flow details

`GET /assessment-flows/:id`

Path parameters

List flow candidates

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

Query parameters

Example response

Assign candidate

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

Example response

Errors

Get Started

Authentication

API Reference

Webhooks

Integration Notes

​List flows

​GET /assessment-flows

​Example request

​Example response

​Create flow

​POST /assessment-flows

​Example request

​Example response

​Update flow

​PATCH /assessment-flows/:id

​Get flow details

​GET /assessment-flows/:id

​Path parameters

​List flow candidates

​GET /assessment-flows/:id/candidates

​Query parameters

​Example response

​Assign candidate

​POST /assessment-flows/:id/assign

​Example response

​Errors

​Related

List flows

`GET /assessment-flows`

Example request

Example response

Create flow

`POST /assessment-flows`

Example request

Example response

Update flow

`PATCH /assessment-flows/:id`

Get flow details

`GET /assessment-flows/:id`

Path parameters

List flow candidates

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

Query parameters

Example response

Assign candidate

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

Example response

Errors

Related