Applications API: Apply, Track Status, and Withdraw

The Applications API is the bridge between job seekers and employers on LWS Job Portal. When a USER applies for a job, a new Application record is created that snapshots their current resumeUrl alongside the coverLetter they provide. The initial status is New. Employers (COMPANY) can then move an application through a defined lifecycle — New → Shortlisted → Interviewed → Hired (or Rejected at any stage). Users can monitor all their submissions with status and date filters, and withdraw any application they own. All applicant listings enforce company ownership so that one company cannot see another’s applicants.

A user must have a résumé uploaded (POST /api/users/resume) before they can submit an application. Applying without one returns 400 Please upload a resume to your profile first.

Application Object

string (UUID)

Unique application identifier.

jobId

string (UUID)

ID of the job applied to.

userId

string (UUID)

ID of the applicant.

status

string

Application lifecycle state — New, Shortlisted, Interviewed, Rejected, or Hired. Default is New.

coverLetter

string (text)

Cover letter submitted with the application.

resumeUrl

string

Snapshot of the applicant’s résumé URL at the time of application.

createdAt

string (ISO 8601)

Timestamp when the application was submitted.

updatedAt

string (ISO 8601)

Timestamp of the most recent status change.

Application Status Lifecycle

Status	Set by	Meaning
`New`	System	Application just submitted, not yet reviewed
`Shortlisted`	Company	Candidate selected for further consideration
`Interviewed`	Company	Candidate has been / is scheduled for an interview
`Rejected`	Company	Application declined
`Hired`	Company	Offer extended and accepted

Endpoints

POST /api/applications/jobs/:jobId/apply

Submit a job application. Requires the user to have a résumé already uploaded to their profile. Prevents duplicate applications to the same job. Auth: Required — Bearer token (USER role)

The resumeUrl is snapshotted from the user’s current profile at submission time. Updating the résumé later does not retroactively change the URL stored on an existing application.

Request

jobId

string (UUID)

required

The UUID of the job to apply for.

coverLetter

string

required

The applicant’s cover letter. Must be a non-empty string. Returns 400 if omitted.

Response

success

boolean

true on successful submission.

data

object

The newly created Application object, including id, jobId, userId, status (New), coverLetter, resumeUrl, createdAt, and updatedAt.

Example

curl -X POST https://api.example.com/api/applications/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012/apply \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "coverLetter": "I am thrilled to apply for the Senior React Developer role. Over the past five years I have built production-grade React applications..."
  }'

{
  "success": true,
  "data": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "jobId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "New",
    "coverLetter": "I am thrilled to apply for the Senior React Developer role...",
    "resumeUrl": "/uploads/resumes/1717689600000-jane-doe-resume.pdf",
    "createdAt": "2024-06-20T10:00:00.000Z",
    "updatedAt": "2024-06-20T10:00:00.000Z"
  }
}

GET /api/applications/my-applications

List all job applications submitted by the authenticated user. Supports filtering by status, applied-date window, and sort direction. Auth: Required — Bearer token (USER role)

Request

status

string

Comma-separated status values to filter by. Example: status=New,Shortlisted. Possible values: New, Shortlisted, Interviewed, Rejected, Hired.

date

string

Applied-date window. Accepted values:

last 7 days
last 30 days
3 months

Omit (or any other value) to return all time.

sort

string

Newest First (default) or Oldest First — sorts by createdAt.

Response

success

boolean

true on success.

count

integer

Total number of applications returned.

data

array

Array of Application objects. Each entry includes a nested job object with its full details, and within the job a nested company object (name, logoUrl, location).

Example

curl "https://api.example.com/api/applications/my-applications?status=New,Shortlisted&date=last+30+days" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "count": 2,
  "data": [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "status": "Shortlisted",
      "coverLetter": "I am thrilled to apply...",
      "resumeUrl": "/uploads/resumes/1717689600000-jane-doe-resume.pdf",
      "createdAt": "2024-06-20T10:00:00.000Z",
      "job": {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "title": "Senior React Developer",
        "slug": "senior-react-developer",
        "type": "Full-time",
        "workMode": "Remote",
        "company": {
          "name": "Acme Corp",
          "logoUrl": "/uploads/logos/acme.png",
          "location": "Dhaka"
        }
      }
    }
  ]
}

GET /api/applications/jobs/:jobId/applicants

List all applicants for a specific job. Only the company that owns the job can call this endpoint. Returns Application records with nested user profile details. Auth: Required — Bearer token (COMPANY role, must own the job)

Request

jobId

string (UUID)

required

The UUID of the job whose applicants to retrieve.

Response

success

boolean

true on success.

data

array

Array of Application objects, each with a nested user object containing id, name, email, title, location, and profilePictureUrl. Sorted by createdAt DESC.

Example

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

{
  "success": true,
  "data": [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "status": "New",
      "coverLetter": "I am thrilled to apply...",
      "resumeUrl": "/uploads/resumes/1717689600000-jane-doe-resume.pdf",
      "createdAt": "2024-06-20T10:00:00.000Z",
      "user": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Jane Doe",
        "email": "jane@example.com",
        "title": "Senior Frontend Developer",
        "location": "Dhaka, Bangladesh",
        "profilePictureUrl": "/uploads/profiles/avatar.jpg"
      }
    }
  ]
}

PATCH /api/applications/:id/status

Update the status of a single application. The company must own the job the application belongs to. The allowed status values are validated server-side. Auth: Required — Bearer token (COMPANY role, must own the job)

Request

string (UUID)

required

The UUID of the application to update.

status

string

required

The new status. Must be one of: New, Shortlisted, Interviewed, Rejected, Hired. Any other value returns 400 Invalid status.

Response

success

boolean

true on successful update.

data

object

The updated Application object.

Example

Shortlist
Reject
Hire

curl -X PATCH https://api.example.com/api/applications/e5f6a7b8-c9d0-1234-efab-345678901234/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"status": "Shortlisted"}'

curl -X PATCH https://api.example.com/api/applications/e5f6a7b8-c9d0-1234-efab-345678901234/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"status": "Rejected"}'

curl -X PATCH https://api.example.com/api/applications/e5f6a7b8-c9d0-1234-efab-345678901234/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"status": "Hired"}'

{
  "success": true,
  "data": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "jobId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "Shortlisted",
    "updatedAt": "2024-06-21T14:30:00.000Z"
  }
}

DELETE /api/applications/:id

Withdraw (permanently delete) an application. Only the user who submitted the application may withdraw it. Once withdrawn, the application is gone and cannot be restored — the user would need to re-apply. Auth: Required — Bearer token (USER role, must own the application)

Request

string (UUID)

required

The UUID of the application to withdraw.

Response

success

boolean

true on successful withdrawal.

message

string

"Application withdrawn successfully"

Example

curl -X DELETE https://api.example.com/api/applications/e5f6a7b8-c9d0-1234-efab-345678901234 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

{
  "success": true,
  "message": "Application withdrawn successfully"
}

Error Reference

Status	Message	Cause
`400`	`Cover letter is required`	`coverLetter` field missing or empty in apply request
`400`	`Please upload a resume to your profile first`	User has no `resumeUrl` stored on their profile
`400`	`You have already applied for this job`	Duplicate application detected for the same `jobId` + `userId`
`400`	`Invalid status`	Status value not in the allowed enum
`401`	`Not authorized, no token`	Missing `Authorization` header
`403`	`User role COMPANY is not authorized…`	`COMPANY` token used on a `USER`-only route
`403`	`Not authorized`	Company does not own the job the application belongs to
`403`	`Not authorized to withdraw this application`	User does not own the application they are trying to delete
`404`	`Job not found`	No job with the given `jobId`
`404`	`Application not found`	No application with the given `id`

Authentication

Resources

Applications API: Apply, Track Status, and Withdraw

Application Object

Application Status Lifecycle

Endpoints

POST /api/applications/jobs/:jobId/apply

Request

Response

Example

GET /api/applications/my-applications

Request

Response

Example

GET /api/applications/jobs/:jobId/applicants

Request

Response

Example

PATCH /api/applications/:id/status

Request

Response

Example

DELETE /api/applications/:id

Request

Response

Example

Error Reference

Build docs developers (and LLMs) love

Authentication

Resources

Documentation Index

​Application Object

​Application Status Lifecycle

​Endpoints

​POST /api/applications/jobs/:jobId/apply

​Request

​Response

​Example

​GET /api/applications/my-applications

​Request

​Response

​Example

​GET /api/applications/jobs/:jobId/applicants

​Request

​Response

​Example

​PATCH /api/applications/:id/status

​Request

​Response

​Example

​DELETE /api/applications/:id

​Request

​Response

​Example

​Error Reference

Build docs developers (and LLMs) love

Application Object

Application Status Lifecycle

Endpoints

POST /api/applications/jobs/:jobId/apply

Request

Response

Example

GET /api/applications/my-applications

Request

Response

Example

GET /api/applications/jobs/:jobId/applicants

Request

Response

Example

PATCH /api/applications/:id/status

Request

Response

Example

DELETE /api/applications/:id

Request

Response

Example

Error Reference