Companies API: Profiles, Jobs, and Dashboard Stats

The Companies API covers everything an employer needs to manage their presence on LWS Job Portal. Private endpoints (protected by COMPANY role auth) let a company read and update its own profile, upload a logo, paginate through posted jobs with status and search filters, browse all applicants across every listing, and retrieve real-time dashboard statistics. Two fully public endpoints serve the candidate-facing experience: a slug-based company profile lookup that includes active job listings, and a separate endpoint that streams only open positions for a given company slug.

A company’s slug is auto-generated from its name at registration and is used as the canonical URL identifier on public-facing routes. If the generated slug is already taken, a numeric suffix is appended (e.g. acme-corp-2).

Company Object

string (UUID)

Unique company identifier.

name

string

Company display name.

slug

string

URL-safe unique slug (e.g. acme-corp).

string

Primary account email.

role

string

Always COMPANY.

industry

string

Industry sector (e.g. "Engineering", "Finance").

description

string (text)

Company overview or about section.

location

string

General location string (for backwards compatibility).

city

string

City.

state

string

State or province.

country

string

Country.

phone

string

Contact phone number.

websiteUrl

string

Company website URL.

hrEmail

string

HR-specific contact email.

infoEmail

string

General information email.

logoUrl

string

Server-relative path to the company logo (e.g. /uploads/logos/acme.png).

employeeCount

string

Headcount range (e.g. "50-200").

foundedYear

integer

Year the company was founded.

JSON object with social media URLs (e.g. { "linkedin": "...", "twitter": "...", "facebook": "..." }).

createdAt

string (ISO 8601)

Account creation timestamp.

updatedAt

string (ISO 8601)

Last-updated timestamp.

Endpoints

GET /api/companies/profile

Fetch the full profile of the currently authenticated company. The password field is excluded. Auth: Required — Bearer token (COMPANY role)

Request

No parameters. Company identity is resolved from the JWT.

Response

success

boolean

true on success.

data

object

Full Company object (password excluded).

Example

curl https://api.example.com/api/companies/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "email": "hr@acme.com",
    "role": "COMPANY",
    "industry": "Engineering",
    "description": "Building the future of software.",
    "city": "Dhaka",
    "country": "Bangladesh",
    "employeeCount": "50-200",
    "foundedYear": 2015,
    "logoUrl": "/uploads/logos/acme.png",
    "websiteUrl": "https://acme.example.com",
    "socialLinks": {
      "linkedin": "https://linkedin.com/company/acme-corp"
    },
    "createdAt": "2024-01-10T08:00:00.000Z",
    "updatedAt": "2024-06-01T10:00:00.000Z"
  }
}

PUT /api/companies/profile

Update the authenticated company’s profile. Only fields included in the request body are changed; omitted fields retain their current values. Auth: Required — Bearer token (COMPANY role)

Request

name

string

Updated company name.

industry

string

Industry sector.

description

string

Company overview.

location

string

General location string.

city

string

City.

state

string

State or province.

country

string

Country.

phone

string

Contact phone number.

websiteUrl

string

Company website URL.

employeeCount

string

Headcount range (e.g. "50-200").

foundedYear

integer

Year founded.

hrEmail

string

HR contact email.

infoEmail

string

General information email.

JSON object with social URLs, e.g. { "linkedin": "...", "twitter": "..." }.

logoUrl

string

Manually set logo URL (prefer the /logo upload endpoint instead).

Response

success

boolean

true on successful update.

data

object

Updated Company object (password excluded).

Example

curl -X PUT https://api.example.com/api/companies/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "We build innovative enterprise software solutions.",
    "employeeCount": "200-500",
    "foundedYear": 2015,
    "websiteUrl": "https://acme.example.com",
    "socialLinks": {
      "linkedin": "https://linkedin.com/company/acme-corp",
      "twitter": "https://twitter.com/acmecorp"
    }
  }'

{
  "success": true,
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Acme Corp",
    "description": "We build innovative enterprise software solutions.",
    "employeeCount": "200-500",
    "foundedYear": 2015,
    "updatedAt": "2024-07-01T11:00:00.000Z"
  }
}

POST /api/companies/logo

Upload a company logo image. Uses multipart/form-data with the file under the field name logo. The image is stored under /uploads/logos/. If the company already has a logo, the old file is deleted from disk before the new one is saved. Auth: Required — Bearer token (COMPANY role)

Request

logo

file

required

The logo image file (JPEG, PNG, etc.). Use Content-Type: multipart/form-data.

Response

success

boolean

true on successful upload.

message

string

"Logo uploaded successfully"

data

object

Updated Company object (password excluded), including the new logoUrl.

Example

curl -X POST https://api.example.com/api/companies/logo \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "logo=@/path/to/acme-logo.png"

{
  "success": true,
  "message": "Logo uploaded successfully",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Acme Corp",
    "logoUrl": "/uploads/logos/1717700000000-acme-logo.png",
    "updatedAt": "2024-06-06T15:13:20.000Z"
  }
}

GET /api/companies/jobs

Retrieve a paginated list of jobs posted by the authenticated company. Supports filtering by status, title search, and sort order. Auth: Required — Bearer token (COMPANY role)

Request

page

integer

default:"1"

Page number.

limit

integer

default:"10"

Results per page.

string

Case-insensitive title search. Example: search=react.

status

string

Filter by job lifecycle status. Must be exactly Active, Closed, or Archived. Omit to return all statuses. Sending an invalid value returns 400.

sort

string

Sort order — newest (default, createdAt DESC) or oldest (createdAt ASC).

Response

success

boolean

true on success.

count

integer

Total matching jobs (for pagination).

totalPages

integer

Total pages.

currentPage

integer

Current page number.

data

array

Array of job objects, each with an applicants count.

Example

curl "https://api.example.com/api/companies/jobs?status=Active&sort=newest&page=1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "count": 8,
  "totalPages": 1,
  "currentPage": 1,
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "title": "Senior React Developer",
      "slug": "senior-react-developer",
      "status": "Active",
      "type": "Full-time",
      "applicants": 14,
      "createdAt": "2024-06-01T08:00:00.000Z"
    }
  ]
}

GET /api/companies/applicants

Retrieve a paginated list of all applicants across every job posted by the authenticated company. Supports filtering by application status, applicant experience level, applicant name search, and applied date range. Auth: Required — Bearer token (COMPANY role)

Request

page

integer

default:"1"

Page number.

limit

integer

default:"10"

Results per page.

status

string

Comma-separated application statuses (case-insensitive). Mapped to: New, Shortlisted, Interviewed, Rejected, Hired. Example: status=shortlisted,interviewed.

experienceLevel

string

Comma-separated experience levels (case-insensitive). Mapped to: Entry, Mid, Senior, Expert, Lead.

string

Filter by applicant name (partial match).

date

string

Applied-date window. Accepted values:

last 7 days
last 30 days
3 months

Omit for no date restriction.

sort

string

newest (default) or oldest — sorts by application createdAt.

Response

success

boolean

true on success.

count

integer

Total matching applications.

totalPages

integer

Total pages.

currentPage

integer

Current page.

data

array

Array of Application objects, each with a nested user object (id, name, email, experienceLevel, profilePictureUrl) and a nested job object (id, title, slug).

Example

curl "https://api.example.com/api/companies/applicants?status=shortlisted&experienceLevel=senior&page=1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "count": 3,
  "totalPages": 1,
  "currentPage": 1,
  "data": [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "status": "Shortlisted",
      "coverLetter": "I am excited to apply for this role...",
      "createdAt": "2024-06-15T09:00:00.000Z",
      "user": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Jane Doe",
        "email": "jane@example.com",
        "experienceLevel": "Senior",
        "profilePictureUrl": "/uploads/profiles/avatar.jpg"
      },
      "job": {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "title": "Senior React Developer",
        "slug": "senior-react-developer"
      }
    }
  ]
}

GET /api/companies/dashboard/stats

Return aggregate statistics for the authenticated company’s recruiting activity. Counts are computed in real time from the database. Auth: Required — Bearer token (COMPANY role)

Request

No parameters.

Response

success

boolean

true on success.

data

object

Show data fields

totalJobs

integer

Total number of jobs ever posted by the company (all statuses).

activeJobs

integer

Jobs currently with status = Active.

totalApplicants

integer

Count of unique users who have applied to any of this company’s jobs.

totalApplications

integer

Total number of individual application submissions.

pendingReviews

integer

Applications with status New (submitted but not yet reviewed).

shortLists

integer

Applications with status Shortlisted.

Example

curl https://api.example.com/api/companies/dashboard/stats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "data": {
    "totalJobs": 12,
    "activeJobs": 5,
    "totalApplicants": 87,
    "totalApplications": 104,
    "pendingReviews": 43,
    "shortLists": 18
  }
}

GET /api/companies/:slug

Fetch a public company profile by slug. Returns the full Company object (password excluded) together with an embedded array of active job listings — each with an applicants count. Auth: None

Request

slug

string

required

The company’s URL slug (e.g. acme-corp).

Response

success

boolean

true when the company is found.

data

object

Company object (password excluded) with a nested jobs array containing only Active listings. Each job includes a nested company object and an applicants count.

Example

curl https://api.example.com/api/companies/acme-corp

{
  "success": true,
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "industry": "Engineering",
    "description": "Building the future of software.",
    "logoUrl": "/uploads/logos/acme.png",
    "employeeCount": "200-500",
    "foundedYear": 2015,
    "jobs": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "title": "Senior React Developer",
        "slug": "senior-react-developer",
        "type": "Full-time",
        "workMode": "Remote",
        "applicants": 14
      }
    ]
  }
}

GET /api/companies/:slug/jobs

Return only the active open positions for a company, identified by slug. Unlike the embedded jobs array on /api/companies/:slug, this endpoint streams a standalone list and is optimised for paginated job boards. Auth: None

Request

slug

string

required

The company’s URL slug.

Response

success

boolean

true on success.

count

integer

Number of active positions returned.

data

array

Array of active job objects, each with a nested company object (name, logoUrl, location, slug) and an applicants count. Sorted by createdAt DESC.

Example

curl https://api.example.com/api/companies/acme-corp/jobs

{
  "success": true,
  "count": 3,
  "data": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "title": "Senior React Developer",
      "slug": "senior-react-developer",
      "type": "Full-time",
      "workMode": "Remote",
      "location": "Dhaka, Bangladesh",
      "experienceLevel": "Senior",
      "salaryMin": 80000,
      "salaryMax": 120000,
      "applicants": 14,
      "company": {
        "name": "Acme Corp",
        "logoUrl": "/uploads/logos/acme.png",
        "location": "Dhaka",
        "slug": "acme-corp"
      }
    }
  ]
}

Error Reference

Status	Message	Cause
`400`	`Please upload a file`	Logo upload request sent without a file
`400`	`Invalid status. Allowed: Active, …`	`status` query param does not match the enum
`400`	`Invalid sort parameter. Allowed: …`	`sort` value not `newest` or `oldest`
`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
`404`	`Company not found`	No company matches the given slug or UUID

Authentication

Resources

Companies API: Profiles, Jobs, and Dashboard Stats

Company Object

Endpoints

GET /api/companies/profile

Request

Response

Example

PUT /api/companies/profile

Request

Response

Example

POST /api/companies/logo

Request

Response

Example

GET /api/companies/jobs

Request

Response

Example

GET /api/companies/applicants

Request

Response

Example

GET /api/companies/dashboard/stats

Request

Response

Example

GET /api/companies/:slug

Request

Response

Example

GET /api/companies/:slug/jobs

Request

Response

Example

Error Reference

Build docs developers (and LLMs) love

Authentication

Resources

Documentation Index

​Company Object

​Endpoints

​GET /api/companies/profile

​Request

​Response

​Example

​PUT /api/companies/profile

​Request

​Response

​Example

​POST /api/companies/logo

​Request

​Response

​Example

​GET /api/companies/jobs

​Request

​Response

​Example

​GET /api/companies/applicants

​Request

​Response

​Example

​GET /api/companies/dashboard/stats

​Request

​Response

​Example

​GET /api/companies/:slug

​Request

​Response

​Example

​GET /api/companies/:slug/jobs

​Request

​Response

​Example

​Error Reference

Build docs developers (and LLMs) love

Company Object

Endpoints

GET /api/companies/profile

Request

Response

Example

PUT /api/companies/profile

Request

Response

Example

POST /api/companies/logo

Request

Response

Example

GET /api/companies/jobs

Request

Response

Example

GET /api/companies/applicants

Request

Response

Example

GET /api/companies/dashboard/stats

Request

Response

Example

GET /api/companies/:slug

Request

Response

Example

GET /api/companies/:slug/jobs

Request

Response

Example

Error Reference