Skip to main content
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

ParameterTypeRequiredDescription
pageNumberintegerNoPage number (default: 1).
perPageintegerNoItems 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

FieldTypeRequiredDescription
titlestringYesAssessment title (1–1000 characters).
hiringForRolestringYesRole being hired for (1–500 characters).
purposeOfInterviewstringYesPurpose or context for the interview (10–5000 characters).
jobIdstringNoJob ID to link this assessment to. Omit or send empty string if not linked to a job.
isEmailVerificationRequiredbooleanNoWhether the candidate must verify email before taking the assessment. Default: true.
statusstringNoACTIVE or INACTIVE. Default: ACTIVE.
durationnumberNoDuration in minutes (1–120). Default: 20.
aiLanguagestringNoLanguage for the interview. Supported: english, spanish, french, german, hindi, and others. Default: english.
skillsarrayNoList of skills (max 20 strings). Default: [].
bucketsarrayNoEvaluation buckets (max 5). Each: name (required), description (optional), status: pass or fail. Default: standard buckets.
shouldEvaluateCEFRbooleanNoEnable 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

ParameterTypeRequiredDescription
assessmentIdstringYesAssessment 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

ParameterTypeRequiredDescription
assessmentIdstringYesAssessment ID.

Request Body (all optional; at least one required)

FieldTypeDescription
titlestringAssessment title (1–1000 characters).
durationnumberDuration in minutes (1–180).
aiLanguagestringLanguage for the interview.
skillsarrayList of skill strings.
purposeOfInterviewstringPurpose 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

ParameterTypeRequiredDescription
assessmentIdstringYesAssessment ID.

Request Body

FieldTypeRequiredDescription
questionstringYesQuestion text (10–1000 characters).
systemInstructionstringNoOptional instructions for evaluating the response.
idealAnswerstringNoOptional 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

ParameterTypeRequiredDescription
assessmentIdstringYesAssessment ID.
questionIdstringYesQuestion ID.

Request Body

FieldTypeRequiredDescription
questionstringYesQuestion text (10–1000 characters).
systemInstructionstringNoOptional instructions for evaluating the response.
idealAnswerstringNoOptional 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

ParameterTypeRequiredDescription
assessmentIdstringYesAssessment ID.
questionIdstringYesQuestion 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.
FieldTypeRequiredDescription
jobIdnumberNo*Job ID. Role and purpose can be taken from the job if not provided.
purposestringNo*Purpose or job description (max 5000 characters). Required if jobId omitted.
rolestringNoRole title (max 500 characters). Optional when using jobId.
typestringNoAssessment 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

ParameterTypeRequiredDescription
assessmentIdstringYesAssessment ID.

Request Body

FieldTypeRequiredDescription
jobDescriptionstringYesJob or role description used to generate questions (min 50 characters).
skillsarrayNoList of skills (at least one recommended).
questionCountnumberNoNumber of questions to generate (1–10). Default: 5.
difficultystringNoeasy, 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

ParameterTypeRequiredDescription
assessmentIdstringYesAssessment ID.

Request Body

FieldTypeRequiredDescription
emailAddressstringYes*Candidate email. Required when jobCandidateId is not provided.
firstNamestringYes*First name. Required when jobCandidateId is not provided.
lastNamestringYes*Last name. Required when jobCandidateId is not provided.
jobCandidateIdnumberNoJob-candidate ID. If provided, name and email can be taken from that candidate.
inviteeTypestringNoCANDIDATE 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

ParameterTypeRequiredDescription
assessmentIdstringYesAssessment ID.

Query Parameters

ParameterTypeRequiredDescription
nextTokenstringNoPagination token from previous response.
limitnumberNoMax 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:
EventWhen it is sent
assessment.readyQuestions have been generated for an assessment (e.g. after auto-generate or generate-questions).
interview.startedA candidate has started an assessment interview.
interview.scoring_completedScoring has finished for an interview submission; includes score and bucket.
interview.endedA candidate has finished or left the interview (completed, timed out, or ended).
interview.errorAn error occurred during the interview (e.g. start failed, scoring failed, permission denied).
interview.complete_laterThe 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.