Assessments - Taptalent Partner API

The Assessments API lets you create voice-based interviews, add or generate questions, invite candidates individually or in bulk, and retrieve submission results, result report PDFs, and shareable result links. 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 AI interview assessments (voice and video) 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": "AI_AUDIO_INTERVIEW",
        "questionCount": 5,
        "hiringForRole": "Senior Software Engineer",
        "purposeOfInterview": "Evaluate technical and communication skills.",
        "duration": 20,
        "aiLanguage": "english",
        "skills": ["JavaScript", "React"],
        "buckets": [],
        "resumeAllowed": false,
        "maxResumeCount": null,
        "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: `arabic`, `bengali`, `bulgarian`, `croatian`, `czech`, `danish`, `dutch`, `english`, `french`, `german`, `greek`, `hebrew`, `hindi`, `hungarian`, `indonesian`, `italian`, `japanese`, `korean`, `malay`, `mandarin`, `polish`, `portuguese`, `russian`, `spanish`, `swedish`, `tagalog`, `thai`, `turkish`, `ukrainian`, `vietnamese`. 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: Strong Fit, Good Fit, Maybe, Not a Fit.
`shouldEvaluateCEFR`	boolean	No	Enable language evaluation for responses. Default: `false`.
`resumeAllowed`	boolean	No	Allow candidates to resume an incomplete interview session (e.g. after network loss or tab closure). Default: not set (treated as `false`).
`maxResumeCount`	number	Conditional	Max times a candidate may resume the same interview (1–5). Required when `resumeAllowed` is `true`. See Interview resume behavior.

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,
  "resumeAllowed": true,
  "maxResumeCount": 2
}

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": "AI_AUDIO_INTERVIEW",
    "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"],
    "resumeAllowed": true,
    "maxResumeCount": 2,
    "assessmentUrl": "https://talent.taptalent.io/apps/start-quiz?testId=testId_1",
    "createdAt": 1234567890000,
    "lastUpdatedOn": 1234567890000
  }
}

Returns 201 Created on success.

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”.
400 – Validation error (e.g. maxResumeCount missing when resumeAllowed is true). code: INVALID_REQUEST.

Get Assessment

Retrieve a single assessment and its user-added questions. The response includes full assessment metadata (resumeAllowed, maxResumeCount, buckets, and other settings) plus question objects as stored in the system. assessmentType is returned as AI_AUDIO_INTERVIEW for voice interviews or AI_VIDEO_INTERVIEW for video interviews.

`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": "AI_AUDIO_INTERVIEW",
    "questionCount": 3,
    "hiringForRole": "Senior Software Engineer",
    "purposeOfInterview": "Evaluate technical and communication skills.",
    "duration": 20,
    "aiLanguage": "english",
    "skills": ["Node.js", "APIs"],
    "resumeAllowed": false,
    "maxResumeCount": null,
    "isEmailVerificationRequired": true,
    "shouldEvaluateCEFR": false,
    "buckets": [],
    "createdAt": 1234567890000,
    "lastUpdatedOn": 1234567890000,
    "createdBy": "clientId_1",
    "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",
        "contextForAI": "Look for structured problem-solving and communication.",
        "idealAnswer": "Candidate should describe architecture, trade-offs, and outcomes.",
        "createdAt": 1234567890000,
        "lastUpdatedAt": 1234567890000,
        "createdByCompanyId": "companyId_1"
      }
    ]
  }
}

Question objects use contextForAI for the evaluation instructions you pass as systemInstruction when adding or updating a question.

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).
`status`	string	`ACTIVE` or `INACTIVE`.
`resumeAllowed`	boolean	Allow candidates to resume an incomplete interview session.
`maxResumeCount`	number	Max resume attempts (1–5). Required when `resumeAllowed` is `true`.

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 AI interview assessment and generate its setup and questions automatically from a job or from role/purpose text. How it works

TapTalent uses AI to generate the assessment setup (title, duration, language, skills, evaluation buckets, and CEFR settings) from the role, purpose, and optional job details.
The assessment is created immediately and returned with questionCount: 0.
Question generation runs in the background. The number of questions is derived from the interview duration and inferred seniority level:
- JUNIOR_MID roles (entry through mid-level IC): about 3 minutes per question
- SENIOR_LEADERSHIP roles (senior, lead, manager, director, executive): about 5 minutes per question
A webhook is sent when questions are ready (see Assessment events).

Your account must have sufficient credits. Creating the assessment consumes 1 credit; background question generation consumes 1 additional credit.

`POST /assessment/auto-generate`

Request Body

Provide at least one of jobId or purpose. When jobId is supplied, role and purpose can be taken from the job if omitted.

Field	Type	Required	Description
`jobId`	number	No*	Job ID. Role, purpose, criteria, and location are taken from the job when not provided.
`purpose`	string	No*	Purpose or job description (max 5000 characters). Required if `jobId` is omitted.
`role`	string	No	Role title (max 500 characters). Optional when using `jobId` (defaults to the job title).
`type`	string	No	`AI_AUDIO_INTERVIEW` (voice) or `AI_VIDEO_INTERVIEW` (video). Default: `AI_AUDIO_INTERVIEW`.
`duration`	number	No	Target interview length in minutes (5–60). Default: 30. AI scopes skills, criteria, and bucket depth to fit this duration.
`resumeAllowed`	boolean	No	Allow candidates to resume an incomplete interview session. Default: `true`. See Interview resume behavior.
`maxResumeCount`	number	Conditional	Max resume attempts (1–5). Default: 3 when `resumeAllowed` is `true`. Required when `resumeAllowed` is `true` if you want to override the default.

*At least one of jobId or purpose is required.

AI-generated setup

The following fields are determined automatically and included in the response. You do not send them in the request.

Field	Description
`testName`	Professional assessment title, typically `{Role} Assessment - {Month Year}`.
`duration`	Final interview duration in minutes (your value, default 30).
`aiLanguage`	Interview language (defaults to `english` unless the role or location implies otherwise).
`shouldEvaluateCEFR`	Whether language proficiency (CEFR) scoring is enabled.
`skills`	3–6 skills to evaluate, derived from the role and purpose.
`buckets`	Four evaluation buckets (pass/fail) tailored to the role, ordered from best fit to not recommended.
`questionCount`	Starts at `0` in the immediate response; updated once background generation completes.

Question count (background step) is computed as round(duration ÷ minutesPerQuestion) with a minimum of 1, using the seniority level inferred during setup.

Request Body Example (from job)

{
  "jobId": 12345,
  "type": "AI_AUDIO_INTERVIEW",
  "duration": 30,
  "resumeAllowed": true,
  "maxResumeCount": 3
}

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",
  "duration": 45
}

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",
    "duration": 30
  }'

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",
    "duration": 45
  }'

Example Response

Returns 201 Created immediately. Questions are still being generated in the background.

{
  "status": "success",
  "message": "Assessment creation initiated. You will receive a webhook when questions are ready.",
  "data": {
    "assessmentId": "assessmentId_1",
    "testName": "Backend Engineer Assessment - Jun 2026",
    "companyId": "companyId_1",
    "jobId": "12345",
    "status": "ACTIVE",
    "assessmentType": "AI_AUDIO_INTERVIEW",
    "questionCount": 0,
    "hiringForRole": "Backend Engineer",
    "purposeOfInterview": "We need a backend engineer who can design APIs and work with Node.js and PostgreSQL.",
    "duration": 30,
    "aiLanguage": "english",
    "skills": ["Node.js", "API Design", "PostgreSQL", "Problem Solving"],
    "buckets": [
      { "name": "Excellent Fit", "description": "Exceeds backend and system design expectations", "color": "green", "status": "pass", "id": 1 },
      { "name": "Strong Candidate", "description": "Meets core backend requirements with minor gaps", "color": "lightGreen", "status": "pass", "id": 2 },
      { "name": "Potential with Development", "description": "Shows aptitude but lacks depth in key areas", "color": "yellow", "status": "pass", "id": 3 },
      { "name": "Not Recommended", "description": "Does not meet essential backend requirements", "color": "red", "status": "fail", "id": 4 }
    ],
    "shouldEvaluateCEFR": false,
    "isEmailVerificationRequired": true,
    "resumeAllowed": true,
    "maxResumeCount": 3,
    "assessmentUrl": "https://talent.taptalent.io/apps/start-quiz?testId=testId_1",
    "createdAt": 1234567890000,
    "lastUpdatedOn": 1234567890000,
    "createdBy": "clientId_1"
  }
}

After background generation completes, poll GET /assessment/:assessmentId or wait for the assessment.ready webhook. For a 30-minute junior/mid-level role, expect about 10 questions; for the same duration at senior/leadership level, expect about 6 questions.

Error Responses

400 – Neither jobId nor purpose provided, or validation error (e.g. duration outside 5–60). code: INVALID_REQUEST.
404 – Job not found or not owned by your company (when jobId is provided). code: NOT_FOUND.
402 – Insufficient credits. code: INSUFFICIENT_CREDITS, errorMessage: “Insufficient credits”.
500 – AI setup or question generation failed. code: AI_GENERATION_FAILED (when applicable).

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.

Bulk Invite Candidates

Invite up to 5,000 candidates to an assessment in a single request. The request is validated and accepted synchronously; invitation emails are then sent in the background. Use the returned batchId with Get Bulk Invite Status to fetch per-candidate outcomes, or listen for the assessment.bulk_invite.completed webhook. Each entry accepts the same fields as Invite Candidate to Assessment, plus an optional externalRef for correlating results with records in your ATS or HRIS—see External reference correlation. To attach an externalRef to a single candidate, send a batch with one entry.

`POST /assessment/:assessmentId/invite/bulk`

Path Parameters

Parameter	Type	Required	Description
`assessmentId`	string	Yes	Assessment ID.

Request Body

Field	Type	Required	Description
`candidates`	array	Yes	1–5,000 invite entries.
`candidates[].emailAddress`	string	Yes*	Candidate email. Required when `jobCandidateId` is not provided.
`candidates[].firstName`	string	Yes*	First name. Required when `jobCandidateId` is not provided.
`candidates[].lastName`	string	Yes*	Last name. Required when `jobCandidateId` is not provided.
`candidates[].jobCandidateId`	number	No	Job-candidate ID. If provided, name and email can be taken from that candidate.
`candidates[].inviteeType`	string	No	`CANDIDATE` or `REVIEWER`. Default: `CANDIDATE`.
`candidates[].externalRef`	string	No	Your own reference for this invite (max 255 characters), e.g. a requisition or application ID from your ATS or HRIS. Stored with the invite and echoed back in batch status, results, and `interview.*` webhook events. Never shown to the candidate.

*If jobCandidateId is omitted, firstName, lastName, and emailAddress are all required for that entry.

Request Body Example

{
  "candidates": [
    { "firstName": "John", "lastName": "Doe", "emailAddress": "john.doe@example.com", "externalRef": "REQ-2025-0042/C-001" },
    { "firstName": "Jane", "lastName": "Smith", "emailAddress": "jane.smith@example.com", "externalRef": "REQ-2025-0042/C-002" },
    { "jobCandidateId": 101, "externalRef": "REQ-2025-0042/C-003" }
  ]
}

Example Request

curl -X POST "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/invite/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidates": [
      { "firstName": "John", "lastName": "Doe", "emailAddress": "john.doe@example.com", "externalRef": "REQ-2025-0042/C-001" },
      { "firstName": "Jane", "lastName": "Smith", "emailAddress": "jane.smith@example.com", "externalRef": "REQ-2025-0042/C-002" },
      { "jobCandidateId": 101, "externalRef": "REQ-2025-0042/C-003" }
    ]
  }'

Example Response

Returns 202 Accepted. Invitation emails are sent in the background.

{
  "status": "success",
  "data": {
    "batchId": "inviteBatchId_1",
    "totalCount": 3
  }
}

totalCount is the number of accepted entries; it matches totalCount in Get Bulk Invite Status and the assessment.bulk_invite.completed webhook payload.

Processing semantics

The request is accepted if the payload is well-formed; individual entries succeed or fail independently (partial success is normal).
Entries whose candidate is already invited are skipped with DUPLICATE_INVITE—they do not fail the batch, and no second email is sent. The same applies when the same email appears twice within one request (the first entry wins).
Interview links are emailed to candidates; they are never returned by the API (same as single invite).
Fetch per-entry outcomes from Get Bulk Invite Status, or wait for the assessment.bulk_invite.completed webhook.

Error Responses

400 – candidates missing, empty, more than 5,000 entries, or an entry is structurally invalid (e.g. no jobCandidateId and missing name/email). code: INVALID_REQUEST. No invites are queued.
404 – Assessment not found. code: NOT_FOUND.
403 – Not allowed to invite for this assessment. code: ACCESS_DENIED.

Get Bulk Invite Status

Retrieve the processing status and per-candidate results for a bulk invite batch.

`GET /assessment/:assessmentId/invite/bulk/:batchId`

Path Parameters

Parameter	Type	Required	Description
`assessmentId`	string	Yes	Assessment ID.
`batchId`	string	Yes	Batch ID returned by Bulk Invite Candidates.

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page of `results` to return (default: 1).
`limit`	number	No	Max `results` entries per page (default: 100, max: 1000).

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/invite/bulk/inviteBatchId_1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "status": "success",
  "data": {
    "batchId": "inviteBatchId_1",
    "batchStatus": "COMPLETED",
    "totalCount": 3,
    "invitedCount": 2,
    "skippedCount": 1,
    "failedCount": 0,
    "results": [
      { "emailAddress": "john.doe@example.com", "externalRef": "REQ-2025-0042/C-001", "status": "INVITED", "inviteId": "invite-token-uuid-1", "code": null, "errorMessage": null },
      { "emailAddress": "jane.smith@example.com", "externalRef": "REQ-2025-0042/C-002", "status": "SKIPPED", "inviteId": null, "code": "DUPLICATE_INVITE", "errorMessage": "Candidate is already invited!" },
      { "jobCandidateId": 101, "emailAddress": "bob.j@example.com", "externalRef": "REQ-2025-0042/C-003", "status": "INVITED", "inviteId": "invite-token-uuid-2", "code": null, "errorMessage": null }
    ],
    "pagination": { "page": 1, "limit": 100, "total": 3, "totalPages": 1 }
  }
}

Field	Type	Description
`batchStatus`	string	`PROCESSING` or `COMPLETED`.
`totalCount` / `invitedCount` / `skippedCount` / `failedCount`	number	Entry counts. `skippedCount` counts duplicates; `failedCount` counts entries that could not be invited.
`results[].status`	string	`INVITED`, `SKIPPED` (duplicate), or `FAILED`.
`results[].inviteId`	string or null	Invite ID when `status` is `INVITED`.
`results[].code`	string or null	`DUPLICATE_INVITE`, `INVALID_REQUEST`, or `NOT_FOUND` (unknown `jobCandidateId`) for skipped/failed entries.
`results[].externalRef`	string or null	Echo of the reference you supplied for this entry.
`pagination`	object	`page`, `limit`, `total`, `totalPages` for the `results` array.

Entries are returned in request order.

Error Responses

404 – Assessment or batch not found, or batch belongs to another assessment. code: NOT_FOUND.
403 – Not allowed to access 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",
        "externalRef": "REQ-2025-0042/C-001",
        "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
    }
  }
}

externalRef echoes the reference supplied when the candidate was invited via Bulk Invite Candidates; it is null when none was provided. See External reference correlation.

Error Responses

403 – Assessment not found or access denied. code: ACCESS_DENIED.

Get Result Report (PDF)

Retrieve a download URL for the PDF result report of a completed submission. The report becomes available once scoring has finished for the submission. Recommended flow: listen for the interview.scoring_completed webhook (it carries the submissionId and your externalRef), then call this endpoint and download the PDF from reportUrl.

`GET /assessment/:assessmentId/submissions/:submissionId/report`

Path Parameters

Parameter	Type	Required	Description
`assessmentId`	string	Yes	Assessment ID.
`submissionId`	string	Yes	Interview submission ID, as delivered in `interview.*` webhook events.

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/submissions/submissionId_1/report" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "status": "success",
  "data": {
    "submissionId": "submissionId_1",
    "reportUrl": "https://cdn.taptalent.io/reports/submissionId_1/report.pdf?signature=...",
    "generatedAt": 1234567890000,
    "expiresAt": 1234567890000
  }
}

Field	Type	Description
`reportUrl`	string	Time-limited URL to the PDF report. Download promptly; request a fresh URL whenever you need the report again. Store the `submissionId`, not the URL.
`generatedAt`	number	Unix timestamp (ms) when the report was generated.
`expiresAt`	number	Unix timestamp (ms) after which `reportUrl` stops working.

Error Responses

409 – Scoring has not completed for this submission yet. code: REPORT_NOT_READY. Retry after receiving interview.scoring_completed.
404 – Assessment or submission not found. code: NOT_FOUND.
403 – Not allowed to access this assessment. code: ACCESS_DENIED.

Get Public Result Link

Retrieve the shareable, public URL for a submission’s result page. Anyone with the link can open it without a TapTalent account. Which sections the page shows (candidate details, AI analysis, interview recording, screening Q&A, proctoring data) is controlled by the assessment’s share configuration, managed in the TapTalent dashboard. Share configuration is not available through this API.

Path Parameters

Parameter	Type	Required	Description
`assessmentId`	string	Yes	Assessment ID.
`submissionId`	string	Yes	Interview submission ID, as delivered in `interview.*` webhook events.

Example Request

curl -X GET "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/submissions/submissionId_1/share-link" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "status": "success",
  "data": {
    "submissionId": "submissionId_1",
    "shareUrl": "https://talent.taptalent.io/apps/quiz-result?id=submissionId_1"
  }
}

Results appear on the page as scoring completes; for a finalized view, fetch the link after interview.scoring_completed.

The link is public: anyone who has it can view the sections permitted by the share configuration. Share it only through channels you trust.

If no share configuration has been saved for the assessment, the public page shows all sections. Review the assessment’s share configuration in the dashboard before distributing links.

Error Responses

404 – Assessment or submission not found. code: NOT_FOUND.
403 – Not allowed to access this assessment. code: ACCESS_DENIED.

Notes

Interview resume behavior

Configure interview resume with resumeAllowed and maxResumeCount when creating or updating an assessment, or when using auto-generate.

If interview resume is enabled (resumeAllowed: true), the candidate can resume the interview from the point where they left off.
A candidate can resume only up to the maximum resume count configured in the assessment settings (maxResumeCount, 1–5 attempts).
If interview resume is disabled (resumeAllowed: false), scoring is processed immediately once the interview is closed, regardless of the reason.
If interview resume is enabled and the candidate loses network connectivity or closes the tab, scoring is not processed until the candidate either resumes and submits the interview or exhausts the allowed resume attempts.

When resume is enabled, interview.scoring_completed and interview.ended webhooks are deferred until scoring runs (after the candidate finishes or uses all resume attempts).

External reference correlation

externalRef is an opaque string (max 255 characters) you can attach to each entry when inviting candidates via Bulk Invite Candidates. TapTalent stores it with the invite and echoes it, unmodified, in:

each entry of Get Bulk Invite Status
each candidate in List Assessment Candidates
every interview.* webhook event for that candidate’s submission

Use it to correlate TapTalent submissions with records in your ATS or HRIS (e.g. a requisition or application ID) without maintaining a lookup table keyed on email. It is never shown to the candidate and never interpreted by TapTalent. To attach an externalRef to a single candidate, send a bulk invite with one entry.

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).
`assessment.bulk_invite.completed`	Processing finished for a bulk invite batch; includes invited/skipped/failed counts.
`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.

​List Assessments

​GET /assessment

​Authentication

​Query Parameters

​Example Request

​Example Response

​Error Responses

​Create Assessment (Voice Interview)

​POST /assessment/audio-interviews

​Request Body

​Request Body Example

​Example Request

​Example Response

​Error Responses

​Get Assessment

​GET /assessment/:assessmentId

​Path Parameters

​Example Request

​Example Response

​Error Responses

​Update Assessment

​PUT /assessment/:assessmentId

​Path Parameters

​Request Body (all optional; at least one required)

​Example Request

​Example Response

​Error Responses

​Add Question

​POST /assessment/:assessmentId/questions

​Path Parameters

​Request Body

​Request Body Example

​Example Request

​Example Response

​Error Responses

​Update Question

​PUT /assessment/:assessmentId/questions/:questionId

​Path Parameters

​Request Body

​Example Request

​Example Response

​Error Responses

​Delete Question

​DELETE /assessment/:assessmentId/questions/:questionId

​Path Parameters

​Example Request

​Example Response

​Error Responses

​Auto-Generate Assessment

​POST /assessment/auto-generate

​Request Body

​AI-generated setup

​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

​Generate Questions for an Assessment

​POST /assessment/:assessmentId/generate-questions

​Path Parameters

​Request Body

​Request Body Example

​Example Request

​Example Response

​Error Responses

​Invite Candidate to Assessment

​POST /assessment/:assessmentId/invite

​Path Parameters

​Request Body

​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

​Bulk Invite Candidates

​POST /assessment/:assessmentId/invite/bulk

​Path Parameters

​Request Body

List Assessments

`GET /assessment`

Authentication

Query Parameters

Example Request

Example Response

Error Responses

Create Assessment (Voice Interview)

`POST /assessment/audio-interviews`

Request Body

Request Body Example

Example Request

Example Response

Error Responses

Get Assessment

`GET /assessment/:assessmentId`

Path Parameters

Example Request

Example Response

Error Responses

Update Assessment

`PUT /assessment/:assessmentId`

Path Parameters

Request Body (all optional; at least one required)

Example Request

Example Response

Error Responses

Add Question

`POST /assessment/:assessmentId/questions`

Path Parameters

Request Body

Request Body Example

Example Request

Example Response

Error Responses

Update Question

`PUT /assessment/:assessmentId/questions/:questionId`

Path Parameters

Request Body

Example Request

Example Response

Error Responses

Delete Question

`DELETE /assessment/:assessmentId/questions/:questionId`

Path Parameters

Example Request

Example Response

Error Responses

Auto-Generate Assessment

`POST /assessment/auto-generate`

Request Body

AI-generated setup

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

Generate Questions for an Assessment

`POST /assessment/:assessmentId/generate-questions`

Path Parameters

Request Body

Request Body Example

Example Request

Example Response

Error Responses

Invite Candidate to Assessment

`POST /assessment/:assessmentId/invite`

Path Parameters

Request Body

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

Bulk Invite Candidates

`POST /assessment/:assessmentId/invite/bulk`

Path Parameters

Request Body