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.
The Assessments API lets you create voice-based interviews, add or generate questions, invite candidates, and view submission results. All requests use the base path /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 via Authorization: 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
curl -X GET "https://partner-api.taptalent.io/v1/partner/assessment?pageNumber=1&perPage=20" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
Example Response
{
"status": "success",
"data": {
"assessments": [
{
"assessmentId": "assessmentId_1",
"testName": "Senior Engineer Interview",
"companyId": "companyId_1",
"jobId": "12345",
"status": "ACTIVE",
"assessmentType": "QUIZ",
"questionCount": 5,
"hiringForRole": "Senior Software Engineer",
"purposeOfInterview": "Evaluate technical and communication skills.",
"duration": 20,
"aiLanguage": "english",
"skills": ["JavaScript", "React"],
"buckets": [],
"createdAt": 1234567890000,
"lastUpdatedOn": 1234567890000,
"createdBy": "clientId_1",
"isEmailVerificationRequired": true,
"shouldEvaluateCEFR": false,
"assessmentUrl": "https://talent.taptalent.io/apps/start-quiz?testId=testId_1",
"postedBy": { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "clientId": "clientId_1" },
"submissionCount": 12
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 5,
"totalPages": 1
}
}
}
Error Responses
Invalid perPage (400):
{
"error": {
"code": "INVALID_PER_PAGE",
"type": "validation_error",
"errorMessage": "perPage must be one of: 10, 20, 40, 80, 100"
}
}
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
{
"title": "Senior Engineer Voice Interview",
"hiringForRole": "Senior Software Engineer",
"purposeOfInterview": "Evaluate technical depth and communication for backend and system design.",
"jobId": "12345",
"isEmailVerificationRequired": true,
"status": "ACTIVE",
"duration": 20,
"aiLanguage": "english",
"skills": ["Node.js", "System Design", "APIs"],
"buckets": [
{ "name": "Strong Fit", "description": "Exceeds expectations", "status": "pass" },
{ "name": "Good Fit", "description": "Meets requirements", "status": "pass" },
{ "name": "Not a Fit", "description": "Does not meet requirements", "status": "fail" }
],
"shouldEvaluateCEFR": false
}
Example Request
curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment/audio-interviews" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Senior Engineer Voice Interview",
"hiringForRole": "Senior Software Engineer",
"purposeOfInterview": "Evaluate technical depth and communication for backend and system design.",
"jobId": "12345",
"isEmailVerificationRequired": true,
"status": "ACTIVE",
"duration": 20,
"aiLanguage": "english",
"skills": ["Node.js", "System Design", "APIs"],
"shouldEvaluateCEFR": false
}'
Example Response
{
"status": "success",
"message": "Assessment created successfully! Add questions to get started.",
"data": {
"assessmentId": "assessmentId_1",
"testName": "Senior Engineer Voice Interview",
"companyId": "companyId_1",
"jobId": "12345",
"status": "ACTIVE",
"assessmentType": "QUIZ",
"questionCount": 0,
"hiringForRole": "Senior Software Engineer",
"purposeOfInterview": "Evaluate technical depth and communication for backend and system design.",
"duration": 20,
"aiLanguage": "english",
"skills": ["Node.js", "System Design", "APIs"],
"assessmentUrl": "https://talent.taptalent.io/apps/start-quiz?testId=testId_1",
"createdAt": 1234567890000,
"lastUpdatedOn": 1234567890000
}
}
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
curl -X GET "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
Example Response
{
"status": "success",
"data": {
"assessmentId": "assessmentId_1",
"testName": "Senior Engineer Voice Interview",
"companyId": "companyId_1",
"jobId": "12345",
"status": "ACTIVE",
"assessmentType": "QUIZ",
"questionCount": 3,
"hiringForRole": "Senior Software Engineer",
"purposeOfInterview": "Evaluate technical and communication skills.",
"duration": 20,
"aiLanguage": "english",
"skills": ["Node.js", "APIs"],
"assessmentUrl": "https://talent.taptalent.io/apps/start-quiz?testId=testId_1",
"questions": [
{
"id": "questionId_1",
"question": "Walk us through a complex system you designed.",
"type": "SUBJECTIVE"
}
]
}
}
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
curl -X PUT "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Updated Interview Title", "duration": 25}'
Example Response
{
"status": "success",
"data": {
"assessmentId": "assessmentId_1",
"message": "Assessment details updated successfully"
}
}
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
{
"question": "Describe a time when you had to debug a critical production issue. What was your approach?",
"systemInstruction": "Look for structured problem-solving and communication.",
"idealAnswer": "Candidate should mention steps like reproduction, root cause, fix, and prevention."
}
Example Request
curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/questions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Describe a time when you had to debug a critical production issue. What was your approach?",
"systemInstruction": "Look for structured problem-solving and communication.",
"idealAnswer": "Candidate should mention steps like reproduction, root cause, fix, and prevention."
}'
Example Response
{
"status": "success",
"data": {
"questionId": "questionId_1",
"message": "Question added successfully"
}
}
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
curl -X PUT "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/questions/questionId_1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "Updated question text here (at least 10 characters)."}'
Example Response
{
"status": "success",
"data": { "message": "Question updated successfully" }
}
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
curl -X DELETE "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/questions/questionId_1" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response
{
"status": "success",
"data": { "message": "Question deleted successfully" }
}
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 either jobId 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. |
*At least one of jobId or purpose is required.
Request Body Example (from job)
{
"jobId": 12345,
"type": "AI_AUDIO_INTERVIEW"
}
Request Body Example (from role and purpose)
{
"purpose": "We need a backend engineer who can design APIs and work with Node.js and PostgreSQL.",
"role": "Backend Engineer",
"type": "AI_VIDEO_INTERVIEW"
}
Example Request (from job)
curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment/auto-generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jobId": 12345, "type": "AI_AUDIO_INTERVIEW"}'
Example Request (from role and purpose)
curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment/auto-generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"purpose": "We need a backend engineer who can design APIs and work with Node.js and PostgreSQL.",
"role": "Backend Engineer",
"type": "AI_VIDEO_INTERVIEW"
}'
Example Response
{
"status": "success",
"message": "Assessment creation initiated. You will receive a webhook when questions are ready.",
"data": {
"assessmentId": "assessmentId_1",
"testName": "Backend Engineer - Voice Interview",
"companyId": "companyId_1",
"jobId": "12345",
"status": "ACTIVE",
"assessmentType": "QUIZ",
"questionCount": 0,
"hiringForRole": "Backend Engineer",
"purposeOfInterview": "We need a backend engineer who can design APIs...",
"duration": 20,
"aiLanguage": "english",
"skills": ["Node.js", "PostgreSQL", "APIs"],
"assessmentUrl": "https://talent.taptalent.io/apps/start-quiz?testId=testId_1",
"createdAt": 1234567890000,
"lastUpdatedOn": 1234567890000
}
}
Error Responses
- 400 – Neither
jobId nor purpose provided. code: INVALID_REQUEST.
- 404 – Job not found (when
jobId is 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
{
"jobDescription": "We are looking for a senior backend engineer with experience in distributed systems, API design, and Node.js. The role involves mentoring and code reviews.",
"skills": ["Node.js", "System Design", "PostgreSQL", "APIs"],
"questionCount": 5,
"difficulty": "medium"
}
Example Request
curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/generate-questions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobDescription": "We are looking for a senior backend engineer with experience in distributed systems, API design, and Node.js. The role involves mentoring and code reviews.",
"skills": ["Node.js", "System Design", "PostgreSQL", "APIs"],
"questionCount": 5,
"difficulty": "medium"
}'
Example Response
{
"status": "success",
"data": {
"message": "Questions generated and added successfully",
"questionCount": 5
}
}
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_FAILED or AI_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 by jobCandidateId; 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. |
*If jobCandidateId is omitted, firstName, lastName, and emailAddress are all required.
Request Body Example (by email and name)
{
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"inviteeType": "CANDIDATE"
}
Request Body Example (by job candidate)
{
"jobCandidateId": 101,
"inviteeType": "CANDIDATE"
}
Example Request (by email and name)
curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/invite" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"inviteeType": "CANDIDATE"
}'
Example Request (by job candidate)
curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/invite" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jobCandidateId": 101, "inviteeType": "CANDIDATE"}'
Example Response
{
"status": "success",
"data": { "inviteId": "invite-token-uuid" }
}
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
jobCandidateId used) 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
curl -X GET "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/candidates?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
Example Response
{
"status": "success",
"data": {
"candidates": [
{
"candidateId": "inviteId_1",
"name": "John Doe",
"email": "john.doe@example.com",
"score": 78.5,
"aiScore": null,
"aiSummary": null,
"status": "finished",
"evaluationStatus": "completed",
"submittedAt": 1234567890000,
"profileImage": null,
"questions": [
{
"id": "questionId_1",
"question": "Describe your experience with system design.",
"userAnswer": "I have led several projects...",
"score": 85,
"aiScore": null,
"reasonOfScore": null,
"type": "SUBJECTIVE"
}
]
}
],
"pagination": {
"nextToken": "base64EncodedTokenOrNull",
"count": 20
}
}
}
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. |
Each webhook payload includes 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.