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)

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

Related Endpoints

• Create Skill Gap Analysis - Start a new analysis
• Get Latest Analysis - Get most recent result
• Get Analysis By ID - Get specific analysis
• Get 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)

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

Related Endpoints

• Get Notification Preference - Read current notification settings
• 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

GET /api/v1/job-seekers?location=Cairo&workPreference=REMOTE&availabilityStatus=OPEN_TO_WORK

2. Get Your Profile

GET /api/v1/job-seekers/me
Authorization: Bearer YOUR_ACCESS_TOKEN

3. Update Your Profile

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

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:

PUT "{uploadUrl}"
Content-Type: image/png
(binary file body)

Response Format

All API responses follow this structure:

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 - Search and filter job seekers
• Get My Profile - View your own profile
• Get Profile By ID - View a specific profile
• Update Profile - Update your profile
• Deactivate Account - Deactivate your account
• Get Notification Preference - Read current notification settings
• 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 - List all work experiences
• Get Work Experience By ID - Get specific work experience
• Create Work Experience - Add new work experience
• Update Work Experience - Update 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 - List all educations
• Get Education By ID - Get specific education
• Create Education - Add new education
• Update Education - Update education
• Delete Education - Remove education