/v1/partner/assessment. When candidates take assessments, you can receive webhooks for interview lifecycle events (start, scoring completed, end, and errors)—see Assessment and interview events in Webhooks.
List Assessments
Get a paginated list of assessments for your company.GET /assessment
Authentication
Requires API key viaAuthorization: Bearer YOUR_API_KEY header.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
pageNumber | integer | No | Page number (default: 1). |
perPage | integer | No | Items per page. Must be one of: 10, 20, 40, 80, 100 (default: 10). |
Example Request
Example Response
Error Responses
Invalid perPage (400):Create Assessment (Voice Interview)
Create a new voice-based interview assessment. You can optionally link it to a job. Your account must have sufficient credits to create an assessment.POST /assessment/audio-interviews
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Assessment title (1–1000 characters). |
hiringForRole | string | Yes | Role being hired for (1–500 characters). |
purposeOfInterview | string | Yes | Purpose or context for the interview (10–5000 characters). |
jobId | string | No | Job ID to link this assessment to. Omit or send empty string if not linked to a job. |
isEmailVerificationRequired | boolean | No | Whether the candidate must verify email before taking the assessment. Default: true. |
status | string | No | ACTIVE or INACTIVE. Default: ACTIVE. |
duration | number | No | Duration in minutes (1–120). Default: 20. |
aiLanguage | string | No | Language for the interview. Supported: english, spanish, french, german, hindi, and others. Default: english. |
skills | array | No | List of skills (max 20 strings). Default: []. |
buckets | array | No | Evaluation buckets (max 5). Each: name (required), description (optional), status: pass or fail. Default: standard buckets. |
shouldEvaluateCEFR | boolean | No | Enable language evaluation for responses. Default: false. |
Request Body Example
Example Request
Example Response
Error Responses
- 404 – Company or job (if provided) not found.
code:NOT_FOUND. - 402 – Insufficient credits.
code:INSUFFICIENT_CREDITS,errorMessage: “Insufficient credits to create assessment”.
Get Assessment
Retrieve a single assessment and its questions.GET /assessment/:assessmentId
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Assessment ID. |
Example Request
Example Response
Error Responses
- 404 – Assessment not found.
code:NOT_FOUND. - 403 – Not allowed to access this assessment.
code:ACCESS_DENIED.
Update Assessment
Update an assessment’s title, duration, language, skills, or purpose. At least one field must be provided.PUT /assessment/:assessmentId
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Assessment ID. |
Request Body (all optional; at least one required)
| Field | Type | Description |
|---|---|---|
title | string | Assessment title (1–1000 characters). |
duration | number | Duration in minutes (1–180). |
aiLanguage | string | Language for the interview. |
skills | array | List of skill strings. |
purposeOfInterview | string | Purpose or context (max 5000 characters). |
Example Request
Example Response
Error Responses
- 400 – No fields provided or validation error.
code:INVALID_REQUEST. - 404 – Assessment not found.
code:NOT_FOUND. - 403 – Not allowed to modify this assessment.
code:ACCESS_DENIED.
Add Question
Add a single question to an assessment.POST /assessment/:assessmentId/questions
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Assessment ID. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
question | string | Yes | Question text (10–1000 characters). |
systemInstruction | string | No | Optional instructions for evaluating the response. |
idealAnswer | string | No | Optional reference or ideal answer. |
Request Body Example
Example Request
Example Response
Error Responses
- 400 – Validation error (e.g. question too short).
code:INVALID_REQUEST. - 404 – Assessment not found.
code:NOT_FOUND. - 403 – Not allowed to modify this assessment.
code:ACCESS_DENIED.
Update Question
Update an existing question on an assessment.PUT /assessment/:assessmentId/questions/:questionId
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Assessment ID. |
questionId | string | Yes | Question ID. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
question | string | Yes | Question text (10–1000 characters). |
systemInstruction | string | No | Optional instructions for evaluating the response. |
idealAnswer | string | No | Optional reference or ideal answer. |
Example Request
Example Response
Error Responses
- 404 – Assessment or question not found, or question not in this assessment.
code:NOT_FOUND. - 403 – Not allowed to modify this assessment.
code:ACCESS_DENIED.
Delete Question
Remove a question from an assessment.DELETE /assessment/:assessmentId/questions/:questionId
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Assessment ID. |
questionId | string | Yes | Question ID. |
Example Request
Example Response
Error Responses
- 404 – Question not found in this assessment.
code:NOT_FOUND. - 403 – Not allowed to modify this assessment.
code:ACCESS_DENIED.
Auto-Generate Assessment
Create an assessment and have questions generated automatically from a job or from role/purpose. You can choose voice-based (audio) or video-based interview. You receive an assessment ID immediately; questions are generated asynchronously. A webhook is sent when questions are ready (see Assessment events). Your account must have sufficient credits.POST /assessment/auto-generate
Request Body
You must provide eitherjobId or purpose.
| Field | Type | Required | Description |
|---|---|---|---|
jobId | number | No* | Job ID. Role and purpose can be taken from the job if not provided. |
purpose | string | No* | Purpose or job description (max 5000 characters). Required if jobId omitted. |
role | string | No | Role title (max 500 characters). Optional when using jobId. |
type | string | No | Assessment type: AI_AUDIO_INTERVIEW (voice-based) or AI_VIDEO_INTERVIEW (video-based). Default: AI_AUDIO_INTERVIEW. |
jobId or purpose is required.
Request Body Example (from job)
Request Body Example (from role and purpose)
Example Request (from job)
Example Request (from role and purpose)
Example Response
Error Responses
- 400 – Neither
jobIdnorpurposeprovided.code:INVALID_REQUEST. - 404 – Job not found (when
jobIdis provided).code:NOT_FOUND. - 402 – Insufficient credits.
code:INSUFFICIENT_CREDITS.
Generate Questions for an Assessment
Generate questions for an existing assessment based on job description and skills. Your account must have sufficient credits. A webhook is sent when generation completes (see Assessment events).POST /assessment/:assessmentId/generate-questions
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Assessment ID. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
jobDescription | string | Yes | Job or role description used to generate questions (min 50 characters). |
skills | array | No | List of skills (at least one recommended). |
questionCount | number | No | Number of questions to generate (1–10). Default: 5. |
difficulty | string | No | easy, medium, or hard. Default: medium. |
Request Body Example
Example Request
Example Response
Error Responses
- 402 – Insufficient credits.
code:INSUFFICIENT_CREDITS,errorMessage: “Insufficient credits to generate questions”. - 403 – Assessment not found or access denied.
code:ACCESS_DENIED. - 500 – Question generation failed or returned no questions.
code:AI_GENERATION_FAILEDorAI_GENERATION_EMPTY.
Invite Candidate to Assessment
Send an assessment invitation to a candidate by email. You can provide candidate details directly or reference an existing job candidate byjobCandidateId; if you use jobCandidateId, name and email can be filled from the candidate record.
POST /assessment/:assessmentId/invite
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Assessment ID. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
emailAddress | string | Yes* | Candidate email. Required when jobCandidateId is not provided. |
firstName | string | Yes* | First name. Required when jobCandidateId is not provided. |
lastName | string | Yes* | Last name. Required when jobCandidateId is not provided. |
jobCandidateId | number | No | Job-candidate ID. If provided, name and email can be taken from that candidate. |
inviteeType | string | No | CANDIDATE or REVIEWER. Default: CANDIDATE. |
jobCandidateId is omitted, firstName, lastName, and emailAddress are all required.
Request Body Example (by email and name)
Request Body Example (by job candidate)
Example Request (by email and name)
Example Request (by job candidate)
Example Response
Error Responses
- 400 – Missing email/name (when not using
jobCandidateId), or invalid/dummy email.code:INVALID_REQUEST. - 400 – Candidate or reviewer already invited.
code:DUPLICATE_INVITE,errorMessage: “Candidate is already invited!” or “Reviewer is already invited!”. - 404 – Assessment or candidate (when
jobCandidateIdused) not found.code:NOT_FOUND. - 403 – Not allowed to invite for this assessment.
code:ACCESS_DENIED.
List Assessment Candidates
Get a paginated list of candidates who have taken the assessment (submitted or timed out), with scores and response details.GET /assessment/:assessmentId/candidates
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
assessmentId | string | Yes | Assessment ID. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
nextToken | string | No | Pagination token from previous response. |
limit | number | No | Max number of results (default: 50). |
Example Request
Example Response
Error Responses
- 403 – Assessment not found or access denied.
code:ACCESS_DENIED.
Notes
Webhooks
To receive real-time notifications for assessments, configure a webhook URL in your partner settings. Once configured, TapTalent will send POST requests to your endpoint for the following events:| Event | When it is sent |
|---|---|
assessment.ready | Questions have been generated for an assessment (e.g. after auto-generate or generate-questions). |
interview.started | A candidate has started an assessment interview. |
interview.scoring_completed | Scoring has finished for an interview submission; includes score and bucket. |
interview.ended | A candidate has finished or left the interview (completed, timed out, or ended). |
interview.error | An error occurred during the interview (e.g. start failed, scoring failed, permission denied). |
interview.complete_later | The candidate chose “Complete later (not recommended)” on the pre-interview setup screen. |
event, timestamp, companyId, and a data object with event-specific fields (e.g. assessmentId, submissionId, interviewStatus). Respond with a 2xx status so TapTalent does not retry the delivery. For payload details, headers, and retry behavior, see Webhook events..png?fit=max&auto=format&n=lKy84_BssSCy2hcz&q=85&s=ac7c949427cc2893306f6036415f087e)