> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taptalent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Assessments

> API endpoints for creating and managing voice-based interviews and assessments

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](/webhooks/events#assessment-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

```bash theme={null}
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

```json theme={null}
{
  "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):

```json theme={null}
{
  "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](#interview-resume-behavior).                                                                                                                                                                                                                               |

### Request Body Example

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
curl -X DELETE "https://partner-api.taptalent.io/v1/partner/assessment/assessmentId_1/questions/questionId_1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "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](/webhooks/events#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)

```json theme={null}
{
  "jobId": 12345,
  "type": "AI_AUDIO_INTERVIEW"
}
```

### Request Body Example (from role and purpose)

```json theme={null}
{
  "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)

```bash theme={null}
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)

```bash theme={null}
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

```json theme={null}
{
  "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](/webhooks/events#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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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)

```json theme={null}
{
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "john.doe@example.com",
  "inviteeType": "CANDIDATE"
}
```

### Request Body Example (by job candidate)

```json theme={null}
{
  "jobCandidateId": 101,
  "inviteeType": "CANDIDATE"
}
```

### Example Request (by email and name)

```bash theme={null}
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)

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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.

#### Interview closure due to network issues, tab closure, or accidental navigation

* 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](/webhooks/events#assessment-events).