Assessments - Taptalent Partner API

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

*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": "AI_AUDIO_INTERVIEW",
    "questionCount": 0,
    "hiringForRole": "Backend Engineer",
    "purposeOfInterview": "We need a backend engineer who can design APIs...",
    "duration": 20,
    "aiLanguage": "english",
    "skills": ["Node.js", "PostgreSQL", "APIs"],
    "resumeAllowed": false,
    "maxResumeCount": null,
    "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

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

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.

Job Candidates Assessment flows

​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

​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

​List Assessment Candidates

​GET /assessment/:assessmentId/candidates

​Path Parameters

​Query Parameters

​Example Request

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

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

List Assessment Candidates

`GET /assessment/:assessmentId/candidates`

Path Parameters

Query Parameters

Example Request