Jobs API

Overview

The Jobs API handles job posting management for employers and job discovery for talent.

Endpoints

Method	Endpoint	Description	Permission
GET	`/api/jobs`	List all jobs	`jobs:read`
GET	`/api/jobs/:id`	Get job details	`jobs:read`
POST	`/api/jobs`	Create job posting	`jobs:write`
PATCH	`/api/jobs/:id`	Update job posting	`jobs:write`
DELETE	`/api/jobs/:id`	Delete job posting	`jobs:delete`
POST	`/api/jobs/:id/apply`	Apply to job	`jobs:apply`

List Jobs

Get paginated list of job postings with optional filters.

Request

GET /api/jobs?page=1&limit=10&status=active&type=full-time

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	10	Items per page
`status`	string	-	Filter by status
`type`	string	-	Filter by job type
`experienceLevel`	string	-	Filter by experience
`remote`	boolean	-	Filter remote jobs
`skills`	string	-	Comma-separated skills
`sortBy`	string	`createdAt`	Sort field
`sortOrder`	string	`desc`	`asc` or `desc`

Response

{
  "data": [
    {
      "id": "job_123",
      "title": "Senior Software Engineer",
      "description": "We are looking for...",
      "company": {
        "id": "company_456",
        "name": "Tech Corp",
        "logo": "https://example.com/logo.png",
        "industry": "technology",
        "size": "51-200"
      },
      "location": "Manila, Philippines",
      "remote": true,
      "salary": {
        "min": 80000,
        "max": 120000,
        "currency": "PHP",
        "period": "monthly"
      },
      "type": "full-time",
      "experienceLevel": "senior",
      "skills": ["React", "TypeScript", "Node.js"],
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  }
}

Get Job Details

Get detailed information about a specific job.

Request

GET /api/jobs/job_123

Response

{
  "id": "job_123",
  "title": "Senior Software Engineer",
  "description": "We are looking for an experienced...",
  "company": {
    "id": "company_456",
    "name": "Tech Corp",
    "logo": "https://example.com/logo.png",
    "industry": "technology",
    "size": "51-200",
    "website": "https://techcorp.com",
    "description": "Leading technology company..."
  },
  "location": "Manila, Philippines",
  "remote": true,
  "salary": {
    "min": 80000,
    "max": 120000,
    "currency": "PHP",
    "period": "monthly"
  },
  "type": "full-time",
  "experienceLevel": "senior",
  "skills": ["React", "TypeScript", "Node.js"],
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Create Job

Create a new job posting (employers only).

Request

POST /api/jobs
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "title": "Senior Software Engineer",
  "description": "We are looking for an experienced...",
  "location": "Manila, Philippines",
  "remote": true,
  "salary": {
    "min": 80000,
    "max": 120000,
    "currency": "PHP",
    "period": "monthly"
  },
  "type": "full-time",
  "experienceLevel": "senior",
  "skills": ["React", "TypeScript", "Node.js"],
  "status": "draft"
}

Request Body

Field	Type	Required	Description
`title`	string	Yes	Job title
`description`	string	Yes	Full job description
`location`	string	Yes	Job location
`remote`	boolean	No	Remote work available
`salary`	object	No	Salary range
`type`	string	Yes	Job type
`experienceLevel`	string	Yes	Required experience
`skills`	string[]	No	Required skills
`status`	string	No	`draft` or `active`

Job Types

full-time
part-time
contract
freelance

Experience Levels

entry
mid
senior
lead
executive

Response

{
  "id": "job_789",
  "title": "Senior Software Engineer",
  "status": "draft",
  "createdAt": "2024-01-15T12:00:00Z"
}

Update Job

Update an existing job posting.

Request

PATCH /api/jobs/job_123
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "title": "Lead Software Engineer",
  "status": "active"
}

Response

{
  "id": "job_123",
  "title": "Lead Software Engineer",
  "status": "active",
  "updatedAt": "2024-01-15T14:00:00Z"
}

Delete Job

Delete a job posting.

Request

DELETE /api/jobs/job_123
Authorization: Bearer <token>

Response

{
  "message": "Job deleted successfully"
}

Apply to Job

Submit an application for a job (talent only).

Request

POST /api/jobs/job_123/apply
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "coverLetter": "I am excited to apply for...",
  "resume": "https://example.com/resume.pdf"
}

Response

{
  "id": "application_456",
  "job": "job_123",
  "status": "pending",
  "appliedAt": "2024-01-15T15:00:00Z"
}

Types

type JobStatus = "draft" | "active" | "paused" | "closed";
type JobType = "full-time" | "part-time" | "contract" | "freelance";
type ExperienceLevel = "entry" | "mid" | "senior" | "lead" | "executive";
 
interface Job {
  id: string;
  title: string;
  description: string;
  company: Company;
  location: string;
  remote: boolean;
  salary?: SalaryRange;
  type: JobType;
  experienceLevel: ExperienceLevel;
  skills: string[];
  status: JobStatus;
  createdAt: string;
  updatedAt: string;
}
 
interface SalaryRange {
  min: number;
  max: number;
  currency: string;
  period: "hourly" | "monthly" | "yearly";
}

Frontend Integration

import { jobsService } from "@/features/jobs";
 
// List jobs
const jobs = await jobsService.getAll({ status: "active" });
 
// Get job details
const job = await jobsService.getById("job_123");
 
// Create job (employer)
const newJob = await jobsService.create({
  title: "Software Engineer",
  description: "...",
  type: "full-time",
  experienceLevel: "mid",
});
 
// Apply to job (talent)
await jobsService.apply("job_123", {
  coverLetter: "...",
  resume: "https://...",
});

On this page