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

# Introduction

> Job Seeker API - Manage job seeker profiles and search candidates.

# Job Seeker API

The Job Seeker API provides endpoints for managing job seeker profiles and searching for candidates.

## Base URL

```
http://localhost:3000/api/v1
```

## Endpoints Overview

| Method | Endpoint                                      | Description                               | Auth Required    |
| ------ | --------------------------------------------- | ----------------------------------------- | ---------------- |
| GET    | `/job-seekers`                                | Get all job seeker profiles (public list) | No               |
| GET    | `/job-seekers/me`                             | Get current user's profile                | Yes (Job Seeker) |
| GET    | `/job-seekers/:id`                            | Get job seeker profile by ID              | No               |
| PATCH  | `/job-seekers/me`                             | Update current user's profile             | Yes (Job Seeker) |
| POST   | `/job-seekers/me/profile-image/presigned-url` | Request profile image upload URL          | Yes (Job Seeker) |
| PUT    | `{uploadUrl}`                                 | Upload profile image to storage           | No (signed URL)  |
| POST   | `/job-seekers/me/profile-image/confirm`       | Confirm profile image upload              | Yes (Job Seeker) |
| DELETE | `/job-seekers/me`                             | Deactivate current user's account         | Yes (Job Seeker) |
| GET    | `/job-seekers/me/notification-preference`     | Get current notification preferences      | Yes (Job Seeker) |
| PATCH  | `/job-seekers/me/notification-preference`     | Update notification preferences           | Yes (Job Seeker) |

## CV Endpoints

| Method | Endpoint              | Description               | Auth Required    |
| ------ | --------------------- | ------------------------- | ---------------- |
| POST   | `/cv/presigned-url`   | Request CV upload URL     | Yes (Job Seeker) |
| PUT    | `{uploadUrl}`         | Upload CV file to storage | No (signed URL)  |
| POST   | `/cv/confirm`         | Confirm CV upload & parse | Yes (Job Seeker) |
| GET    | `/cv/me`              | Get current CV info       | Yes (Job Seeker) |
| GET    | `/cv/me/download-url` | Get CV download URL       | Yes (Job Seeker) |
| DELETE | `/cv/me`              | Delete current CV         | Yes (Job Seeker) |
| GET    | `/cv-parse/preview`   | Preview parsed CV data    | Yes (Job Seeker) |
| POST   | `/cv-parse/confirm`   | Confirm & save to profile | Yes (Job Seeker) |

**CV Upload Flow:** Request URL -> Upload File -> Confirm Upload -> NLP Parsing

**CV Parse Flow:** Preview Parsed Data -> Confirm & Save to Profile

> **Note:** Skills extracted from CV have `verified: true` flag indicating they were parsed from the CV document.

See detailed documentation for each endpoint in the API Reference section.

## Work Experience Endpoints

| Method | Endpoint                                  | Description               | Auth Required       |
| ------ | ----------------------------------------- | ------------------------- | ------------------- |
| GET    | `/job-seekers/me/work-experiences`        | Get all work experiences  | Yes (Authenticated) |
| GET    | `/job-seekers/me/work-experiences/:expId` | Get work experience by ID | Yes (Authenticated) |
| POST   | `/job-seekers/me/work-experiences`        | Create work experience    | Yes (Authenticated) |
| PATCH  | `/job-seekers/me/work-experiences/:expId` | Update work experience    | Yes (Authenticated) |
| DELETE | `/job-seekers/me/work-experiences/:expId` | Delete work experience    | Yes (Authenticated) |

## Education Endpoints

| Method | Endpoint                                  | Description         | Auth Required       |
| ------ | ----------------------------------------- | ------------------- | ------------------- |
| GET    | `/job-seekers/me/educations`              | Get all educations  | Yes (Authenticated) |
| GET    | `/job-seekers/me/educations/:educationId` | Get education by ID | Yes (Authenticated) |
| POST   | `/job-seekers/me/educations`              | Create education    | Yes (Authenticated) |
| PATCH  | `/job-seekers/me/educations/:educationId` | Update education    | Yes (Authenticated) |
| DELETE | `/job-seekers/me/educations/:educationId` | Delete education    | Yes (Authenticated) |

## Skill Gap Analysis Endpoints

| Method | Endpoint                                 | Description                    | Auth Required    |
| ------ | ---------------------------------------- | ------------------------------ | ---------------- |
| POST   | `/job-seekers/me/skill-analysis`         | Create new skill gap analysis  | Yes (Job Seeker) |
| GET    | `/job-seekers/me/skill-analysis/latest`  | Get latest analysis result     | Yes (Job Seeker) |
| GET    | `/job-seekers/me/skill-analysis/:id`     | Get analysis by ID             | Yes (Job Seeker) |
| GET    | `/job-seekers/me/skill-analysis/history` | Get paginated analysis history | Yes (Job Seeker) |

<Info>
  **Weekly Limit:** Job seekers can create up to 10 skill gap analyses per week. The limit resets on
  Monday.
</Info>

### Related Endpoints

* [Create Skill Gap Analysis](/api-reference/job-seeker/create-skill-gap-analysis) - Start a new analysis
* [Get Latest Analysis](/api-reference/job-seeker/get-latest-skill-gap-analysis) - Get most recent result
* [Get Analysis By ID](/api-reference/job-seeker/get-skill-gap-analysis-by-id) - Get specific analysis
* [Get Analysis History](/api-reference/job-seeker/get-skill-gap-analysis-history) - List all analyses

## Notification Preference Endpoints

| Method | Endpoint                                  | Description                          | Auth Required    |
| ------ | ----------------------------------------- | ------------------------------------ | ---------------- |
| GET    | `/job-seekers/me/notification-preference` | Get current notification preferences | Yes (Job Seeker) |
| PATCH  | `/job-seekers/me/notification-preference` | Update notification preferences      | Yes (Job Seeker) |

<Info>
  **Default Values**: Notification preferences are initialized automatically with both settings
  enabled the first time the job seeker reads them.
</Info>

### Related Endpoints

* [Get Notification Preference](/api-reference/job-seeker/get-notification-preference) - Read current notification settings
* [Update Notification Preference](/api-reference/job-seeker/update-notification-preference) - Change notification settings

## Common Enums

### Availability Status

| Value               | Description                                    |
| ------------------- | ---------------------------------------------- |
| `OPEN_TO_WORK`      | Actively looking for job opportunities         |
| `NOT_LOOKING`       | Not currently looking for jobs                 |
| `PASSIVELY_LOOKING` | Open to opportunities but not actively looking |
| `EMPLOYED`          | Currently employed, open to opportunities      |
| `UNAVAILABLE`       | Not available for work                         |

### Work Preference

| Value    | Description                     |
| -------- | ------------------------------- |
| `REMOTE` | Prefers remote work             |
| `ONSITE` | Prefers on-site work            |
| `HYBRID` | Prefers hybrid work arrangement |
| `ANY`    | No specific preference          |

### Job Type

| Value        | Description                 |
| ------------ | --------------------------- |
| `FULL_TIME`  | Full-time position          |
| `PART_TIME`  | Part-time position          |
| `CONTRACT`   | Contract/Temporary position |
| `INTERNSHIP` | Internship position         |
| `FREELANCE`  | Freelance work              |

## Quick Start

### 1. Search for Job Seekers

```bash theme={null}
GET /api/v1/job-seekers?location=Cairo&workPreference=REMOTE&availabilityStatus=OPEN_TO_WORK
```

### 2. Get Your Profile

```bash theme={null}
GET /api/v1/job-seekers/me
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### 3. Update Your Profile

```bash theme={null}
PATCH /api/v1/job-seekers/me
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "title": "Senior Software Engineer",
  "location": "Cairo, Egypt",
  "summary": "Experienced developer..."
}
```

### 4. Upload Profile Image

```bash theme={null}
POST /api/v1/job-seekers/me/profile-image/presigned-url
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "fileName": "avatar.png",
  "mimeType": "image/png"
}
```

Then upload the returned `uploadUrl` with:

```bash theme={null}
PUT "{uploadUrl}"
Content-Type: image/png
(binary file body)
```

## Response Format

All API responses follow this structure:

```typescript theme={null}
interface ApiResponse<T> {
  success: boolean;
  data: T;
  message: string;
  meta: {
    timestamp: string;
    path: string;
    method: string;
  };
}
```

## Pagination

List endpoints support pagination:

| Parameter | Type   | Default | Description    |
| --------- | ------ | ------- | -------------- |
| `page`    | number | 1       | Page number    |
| `limit`   | number | 20      | Items per page |

Response includes:

* `total`: Total number of items
* `page`: Current page
* `limit`: Items per page
* `totalPages`: Total number of pages

## Filtering

The `/job-seekers` endpoint supports filters:

| Parameter              | Type    | Description                        |
| ---------------------- | ------- | ---------------------------------- |
| `availabilityStatus`   | enum    | Filter by availability status      |
| `location`             | string  | Filter by location (partial match) |
| `workPreference`       | enum    | Filter by work preference          |
| `minYearsOfExperience` | number  | Minimum years of experience        |
| `maxYearsOfExperience` | number  | Maximum years of experience        |
| `preferredJobTypes`    | enum\[] | Filter by job types                |
| `maxNoticePeriod`      | number  | Maximum notice period (days)       |

## Related Endpoints

* [Get All Profiles](/api-reference/job-seeker/get-all-profiles) - Search and filter job seekers
* [Get My Profile](/api-reference/job-seeker/get-my-profile) - View your own profile
* [Get Profile By ID](/api-reference/job-seeker/get-profile-by-id) - View a specific profile
* [Update Profile](/api-reference/job-seeker/update-profile) - Update your profile
* [Deactivate Account](/api-reference/job-seeker/deactivate-account) - Deactivate your account
* [Get Notification Preference](/api-reference/job-seeker/get-notification-preference) - Read current notification settings
* [Update Notification Preference](/api-reference/job-seeker/update-notification-preference) - Change notification settings

## Work Experience

Work experience entries allow job seekers to showcase their professional history including company names, job titles, employment dates, and descriptions.

### Fields

| Field         | Type    | Required | Description                          |
| ------------- | ------- | -------- | ------------------------------------ |
| `companyName` | string  | Yes      | Name of the company                  |
| `jobTitle`    | string  | Yes      | Title of the position                |
| `description` | string  | No       | Job description and responsibilities |
| `location`    | string  | No       | Work location                        |
| `startDate`   | string  | Yes      | Start date (ISO 8601 format)         |
| `endDate`     | string  | No       | End date (ISO 8601 format)           |
| `isCurrent`   | boolean | Yes      | Currently working here               |

### Related Endpoints

* [Get All Work Experiences](/api-reference/work-experience/get-all-work-experiences) - List all work experiences
* [Get Work Experience By ID](/api-reference/work-experience/get-work-experience-by-id) - Get specific work experience
* [Create Work Experience](/api-reference/work-experience/create-work-experience) - Add new work experience
* [Update Work Experience](/api-reference/work-experience/update-work-experience) - Update work experience
* [Delete Work Experience](/api-reference/work-experience/delete-work-experience) - Remove work experience

## Education

Education entries allow job seekers to showcase their academic background, including institution name, degree type, field of study, and dates.

### Fields

| Field             | Type    | Required | Description                  |
| ----------------- | ------- | -------- | ---------------------------- |
| `institutionName` | string  | Yes      | Name of the institution      |
| `degreeType`      | enum    | Yes      | Type of degree obtained      |
| `fieldOfStudy`    | string  | Yes      | Field of study               |
| `description`     | string  | No       | Additional education details |
| `gpa`             | number  | No       | GPA (0-4 scale)              |
| `startDate`       | string  | Yes      | Start date (ISO 8601 format) |
| `endDate`         | string  | No       | End date (ISO 8601 format)   |
| `isCurrent`       | boolean | Yes      | Currently studying here      |

### Degree Type Enum

| Value           | Description                 |
| --------------- | --------------------------- |
| `HIGH_SCHOOL`   | High school diploma         |
| `ASSOCIATE`     | Associate degree            |
| `BACHELOR`      | Bachelor's degree           |
| `MASTER`        | Master's degree             |
| `PHD`           | Doctorate/PhD               |
| `BOOTCAMP`      | Coding bootcamp certificate |
| `CERTIFICATION` | Professional certification  |
| `OTHER`         | Other type of education     |

### Related Endpoints

* [Get All Educations](/api-reference/education/get-all-educations) - List all educations
* [Get Education By ID](/api-reference/education/get-education-by-id) - Get specific education
* [Create Education](/api-reference/education/create-education) - Add new education
* [Update Education](/api-reference/education/update-education) - Update education
* [Delete Education](/api-reference/education/delete-education) - Remove education