Jobs API: List, Search, Create, and Manage Listings

The Jobs API is the core of LWS Job Portal. Public visitors can browse and search the full catalogue of active listings with rich filtering — by employment type, work mode, experience level, salary range, and skills — or look up a specific posting by its human-readable slug. Authenticated job seekers (USER) unlock a personalised recommendation feed scored against their profile’s skills and experience level. Authenticated employers (COMPANY) can create, edit, and delete their own postings. Every job carries an auto-generated slug derived from its title, a status lifecycle (Active, Closed, Archived), and a JSON skills array used for both filtering and recommendations.

All list endpoints that return job arrays also include a nested company object (id, name, logoUrl, location) and an applicants count derived from the associated applications. The raw applications array is stripped from the response automatically.

Job Object

string (UUID)

Unique job identifier.

companyId

string (UUID)

ID of the owning company.

title

string

Job title.

slug

string

URL-safe unique slug auto-generated from the title (e.g. senior-react-developer-1).

type

string

Employment type — Full-time, Part-time, Contract, Freelance, or Internship.

workMode

string

Work arrangement — Remote, On-site, or Hybrid.

location

string

City or region of the role.

salaryMin

integer

Lower bound of the salary range.

salaryMax

integer

Upper bound of the salary range.

salaryPeriod

string

Hourly, Daily, Weekly, Monthly, or Yearly.

description

string (text)

Full job description.

Endpoints

GET /api/jobs

Retrieve a paginated list of active job listings. Supports full-text search across titles and skills, multi-value enum filters, and salary range constraints. Auth: None

Request

page

integer

default:"1"

Page number for pagination.

limit

integer

default:"10"

Number of results per page.

string

Case-insensitive full-text search. Matched against title and the skills JSON array (cast to text). Example: search=react developer.

type

string

Comma-separated employment types. Case-insensitive. Allowed values: Full-time, Part-time, Contract, Freelance, Internship. Example: type=full-time,contract.

experienceLevel

string

Comma-separated experience levels. Case-insensitive. Allowed values: Entry, Mid, Senior, Expert, Lead. Example: experienceLevel=mid,senior.

skills

string

Comma-separated skill names. A job matches if any of the requested skills appear in its skills array. Example: skills=React,TypeScript.

minSalary

integer

Filter to jobs where salaryMin is at or above this value. Example: minSalary=50000.

maxSalary

integer

Filter to jobs where salaryMax is at or below this value. Example: maxSalary=120000.

sort

string

Sort order. Options:

recent (default) — newest first by createdAt
salary_high — highest salaryMax first
salary_low — lowest salaryMin first

Response

success

boolean

true on success.

count

integer

Total number of jobs matching the filters (used for pagination math).

totalPages

integer

Total number of pages given the current limit.

currentPage

integer

The page number returned.

data

array

Array of job objects, each with a nested company object and an applicants count.

Example

curl "https://api.example.com/api/jobs?search=react&type=full-time&experienceLevel=mid,senior&page=1&limit=10&sort=salary_high"

{
  "success": true,
  "count": 42,
  "totalPages": 5,
  "currentPage": 1,
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "title": "Senior React Developer",
      "slug": "senior-react-developer",
      "type": "Full-time",
      "workMode": "Remote",
      "location": "Dhaka, Bangladesh",
      "salaryMin": 80000,
      "salaryMax": 120000,
      "salaryPeriod": "Yearly",
      "category": "Engineering",
      "experienceLevel": "Senior",
      "skills": ["React", "TypeScript", "Redux"],
      "status": "Active",
      "applicants": 14,
      "company": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Acme Corp",
        "logoUrl": "/uploads/logos/acme.png",
        "location": "Dhaka"
      },
      "createdAt": "2024-06-01T08:00:00.000Z",
      "updatedAt": "2024-06-01T08:00:00.000Z"
    }
  ]
}

GET /api/jobs/recommendations

Return a personalised list of active jobs scored against the authenticated user’s skills and experienceLevel. Each skill match contributes 2 points; an exact experienceLevel match contributes 5 points. Jobs with a score of 0 are excluded. Results are sorted by descending score. Auth: Required — Bearer token (USER role)

To receive useful recommendations, the user should populate skills and experienceLevel on their profile first via PUT /api/users/profile. An empty profile returns an empty array immediately.

Request

No query parameters. The user’s profile is read from the JWT-resolved req.user.

Response

success

boolean

true on success.

data

array

Scored and sorted array of active job objects, each with a nested company object (name, logoUrl, location). Returns [] if the user has no skills and no experience level set.

Example

curl https://api.example.com/api/jobs/recommendations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "title": "Senior React Developer",
      "slug": "senior-react-developer",
      "experienceLevel": "Senior",
      "skills": ["React", "TypeScript"],
      "company": {
        "name": "Acme Corp",
        "logoUrl": "/uploads/logos/acme.png",
        "location": "Dhaka"
      }
    }
  ]
}

GET /api/jobs/:slug

Fetch a single job by its URL slug. Returns the full job object including the full company profile (password excluded) and an applicants count. Auth: None

Request

slug

string

required

The unique URL-safe slug of the job (e.g. senior-react-developer).

Response

success

boolean

true when the job is found.

data

object

Full job object with a nested company object (all fields, password excluded) and applicants count.

Example

curl https://api.example.com/api/jobs/senior-react-developer

{
  "success": true,
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "title": "Senior React Developer",
    "slug": "senior-react-developer",
    "type": "Full-time",
    "workMode": "Remote",
    "location": "Dhaka, Bangladesh",
    "salaryMin": 80000,
    "salaryMax": 120000,
    "salaryPeriod": "Yearly",
    "description": "We are looking for a skilled Senior React Developer...",
    "requirements": "5+ years of experience with React...",
    "benefits": "Health insurance, 20 days PTO...",
    "skills": ["React", "TypeScript", "Redux"],
    "status": "Active",
    "applicants": 14,
    "deadline": "2024-08-31T00:00:00.000Z",
    "vacancies": 2,
    "company": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "email": "hr@acme.com",
      "industry": "Engineering",
      "logoUrl": "/uploads/logos/acme.png"
    }
  }
}

GET /api/jobs/:id/similar

Return up to 5 active jobs similar to the specified job, matched by shared category or overlapping skills. The current job is excluded from results. Auth: None

This endpoint takes the job’s UUID (:id), not its slug. Route ordering in Express means /:id/similar is registered before /:slug, so numeric or UUID-like values resolve here first.

Request

string (UUID)

required

The UUID of the reference job.

Response

success

boolean

true on success.

count

integer

Number of similar jobs returned (0–5).

data

array

Array of similar job objects, each with a nested company object (name, logoUrl, location).

Example

curl https://api.example.com/api/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012/similar

{
  "success": true,
  "count": 3,
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "title": "React Frontend Engineer",
      "slug": "react-frontend-engineer",
      "category": "Engineering",
      "skills": ["React", "CSS", "JavaScript"],
      "company": {
        "name": "StartupXYZ",
        "logoUrl": "/uploads/logos/startupxyz.png",
        "location": "Remote"
      }
    }
  ]
}

POST /api/jobs

Create a new job listing under the authenticated company’s account. The slug is auto-generated from the title and deduplicated with a numeric suffix if needed. Auth: Required — Bearer token (COMPANY role)

Request

title

string

required

Job title (e.g. "Senior React Developer"). Used to generate the slug.

type

string

required

Employment type. Must be one of: Full-time, Part-time, Contract, Freelance, Internship.

workMode

string

required

Work arrangement. Must be one of: Remote, On-site, Hybrid.

location

string

required

City or region for the role.

description

string

required

Full job description (plain text or markdown).

Response

success

boolean

true on successful creation.

data

object

The newly created job object including the generated slug and id.

Example

curl -X POST https://api.example.com/api/jobs \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior React Developer",
    "type": "Full-time",
    "workMode": "Remote",
    "location": "Dhaka, Bangladesh",
    "description": "We are looking for an experienced React developer...",
    "category": "Engineering",
    "experienceLevel": "Senior",
    "salaryMin": 80000,
    "salaryMax": 120000,
    "salaryPeriod": "Yearly",
    "skills": ["React", "TypeScript", "Redux"],
    "vacancies": 2,
    "deadline": "2024-08-31"
  }'

{
  "success": true,
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "companyId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "title": "Senior React Developer",
    "slug": "senior-react-developer",
    "type": "Full-time",
    "workMode": "Remote",
    "status": "Active",
    "createdAt": "2024-06-10T12:00:00.000Z",
    "updatedAt": "2024-06-10T12:00:00.000Z"
  }
}

PUT /api/jobs/:id

Update an existing job listing. Only the company that owns the job may update it. Pass only the fields you want to change — the entire req.body is diffed against the existing record. Auth: Required — Bearer token (COMPANY role, must own the job)

Request

string (UUID)

required

UUID of the job to update.

title

string

Updated job title.

type

string

Updated employment type.

workMode

string

Updated work arrangement.

location

string

Updated location.

description

string

Updated description.

Response

success

boolean

true on successful update.

data

object

The updated job object.

Example

curl -X PUT https://api.example.com/api/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Closed",
    "vacancies": 0
  }'

{
  "success": true,
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "status": "Closed",
    "vacancies": 0,
    "updatedAt": "2024-07-01T09:00:00.000Z"
  }
}

DELETE /api/jobs/:id

Permanently delete a job listing and all associated data. Only the owning company may delete it. Auth: Required — Bearer token (COMPANY role, must own the job)

Request

string (UUID)

required

UUID of the job to delete.

Response

success

boolean

true on successful deletion.

message

string

"Job removed"

Example

curl -X DELETE https://api.example.com/api/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "message": "Job removed"
}

Error Reference

Status	Message	Cause
`401`	`Not authorized, no token`	Missing `Authorization` header on protected route
`403`	`User role USER is not authorized…`	`USER` token used on a `COMPANY`-only route
`403`	`Not authorized to update this job`	Company token does not own the specified job
`403`	`Not authorized to delete this job`	Company token does not own the specified job
`404`	`Job not found`	No job exists with the given slug or UUID

Authentication

Resources

Jobs API: List, Search, Create, and Manage Listings

Job Object

Endpoints

GET /api/jobs

Request

Response

Example

GET /api/jobs/recommendations

Request

Response

Example

GET /api/jobs/:slug

Request

Response

Example

GET /api/jobs/:id/similar

Request

Response

Example

POST /api/jobs

Request

Response

Example

PUT /api/jobs/:id

Request

Response

Example

DELETE /api/jobs/:id

Request

Response

Example

Error Reference

Build docs developers (and LLMs) love

Authentication

Resources

Documentation Index

​Job Object

​Endpoints

​GET /api/jobs

​Request

​Response

​Example

​GET /api/jobs/recommendations

​Request

​Response

​Example

​GET /api/jobs/:slug

​Request

​Response

​Example

​GET /api/jobs/:id/similar

​Request

​Response

​Example

​POST /api/jobs

​Request

​Response

​Example

​PUT /api/jobs/:id

​Request

​Response

​Example

​DELETE /api/jobs/:id

​Request

​Response

​Example

​Error Reference

Build docs developers (and LLMs) love

Job Object

Endpoints

GET /api/jobs

Request

Response

Example

GET /api/jobs/recommendations

Request

Response

Example

GET /api/jobs/:slug

Request

Response

Example

GET /api/jobs/:id/similar

Request

Response

Example

POST /api/jobs

Request

Response

Example

PUT /api/jobs/:id

Request

Response

Example

DELETE /api/jobs/:id

Request

Response

Example

Error Reference