Skip to main content

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 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):
FieldTypeRequiredDescription
flowNamestringYesName of the flow
descriptionstringNoOptional description
stepsarrayYesAt least one step
Each step:
FieldTypeRequiredDescription
assessmentIdstringYesExisting assessment (test) id
passThresholdnumberYes0–100
assessmentType / typestringNoIf omitted, resolved from the assessment record
name, instructions, passActionstringNoOptional 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

ParameterDescription
idFlow 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

ParameterTypeDescription
pageintegerPage number (default 1)
pageSize or perPageintegerPage size (default 10, max 100)
searchstringSubstring match on candidate name or email
statusstringOne 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):
FieldTypeRequiredDescription
emailstringYes*Candidate email (*unless jobCandidateId is provided)
firstName, lastNamestringNoUsed when inviting by email
jobCandidateIdnumber/stringNoJob candidate id
jobIdnumber/stringNoOptional job context
talentIdnumber/stringNoOptional

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