Applications API

Overview

The Applications API manages job applications through the hiring pipeline, from submission to hiring decision.

Endpoints

Method	Endpoint	Description	Permission
GET	`/api/applications`	List applications	`applications:read`
GET	`/api/applications/:id`	Get application details	`applications:read`
PATCH	`/api/applications/:id`	Update application status	`applications:review`
DELETE	`/api/applications/:id`	Withdraw application	`applications:write`

Application Status Flow

pending → reviewing → interview → trial → offered → hired
                ↓         ↓         ↓        ↓
             rejected  rejected  rejected  rejected

Status	Description
`pending`	Application submitted, awaiting review
`reviewing`	Under review by employer
`interview`	Scheduled for interview
`trial`	In trial period
`offered`	Job offer extended
`hired`	Offer accepted, hired
`rejected`	Application rejected

List Applications

Get applications with optional filters.

Request (Talent)

GET /api/applications?status=pending
Authorization: Bearer <token>

Request (Employer)

GET /api/applications?jobId=job_123&status=reviewing
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Description
`jobId`	string	Filter by job (employer)
`status`	string	Filter by status
`page`	number	Page number
`limit`	number	Items per page

Response

{
  "data": [
    {
      "id": "app_123",
      "job": {
        "id": "job_456",
        "title": "Senior Software Engineer",
        "company": {
          "id": "company_789",
          "name": "Tech Corp"
        }
      },
      "applicant": {
        "id": "user_101",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com"
      },
      "status": "reviewing",
      "coverLetter": "I am excited to apply...",
      "resume": "https://example.com/resume.pdf",
      "appliedAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-16T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

Get Application Details

Get detailed information about a specific application.

Request

GET /api/applications/app_123
Authorization: Bearer <token>

Response

{
  "id": "app_123",
  "job": {
    "id": "job_456",
    "title": "Senior Software Engineer",
    "description": "We are looking for...",
    "company": {
      "id": "company_789",
      "name": "Tech Corp",
      "logo": "https://example.com/logo.png"
    },
    "location": "Manila, Philippines",
    "type": "full-time"
  },
  "applicant": {
    "id": "user_101",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "avatar": "https://example.com/avatar.jpg"
  },
  "status": "reviewing",
  "coverLetter": "I am excited to apply for this position...",
  "resume": "https://example.com/resume.pdf",
  "appliedAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T09:00:00Z"
}

Update Application Status

Update the status of an application (employer only).

Request

PATCH /api/applications/app_123
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "status": "interview"
}

Valid Status Transitions

From	To
`pending`	`reviewing`, `rejected`
`reviewing`	`interview`, `rejected`
`interview`	`trial`, `rejected`
`trial`	`offered`, `rejected`
`offered`	`hired`, `rejected`

Response

{
  "id": "app_123",
  "status": "interview",
  "updatedAt": "2024-01-17T14:00:00Z"
}

Withdraw Application

Withdraw an application (talent only).

Request

DELETE /api/applications/app_123
Authorization: Bearer <token>

Response

{
  "message": "Application withdrawn successfully"
}

Types

type ApplicationStatus =
  | "pending"
  | "reviewing"
  | "interview"
  | "trial"
  | "offered"
  | "hired"
  | "rejected";
 
interface Application {
  id: string;
  job: Job;
  applicant: User;
  status: ApplicationStatus;
  coverLetter?: string;
  resume?: string;
  appliedAt: string;
  updatedAt: string;
}

Frontend Integration

import { applicationsService } from "@/features/applications";
 
// List my applications (talent)
const myApplications = await applicationsService.getMyApplications();
 
// List applications for a job (employer)
const jobApplications = await applicationsService.getForJob("job_123");
 
// Update status (employer)
await applicationsService.updateStatus("app_123", "interview");
 
// Withdraw application (talent)
await applicationsService.withdraw("app_123");

Permission Matrix

Action	ADMIN	EMPLOYER	TALENT
View own applications	✓	-	✓
View job applications	✓	✓ (own jobs)	-
Update status	✓	✓ (own jobs)	-
Withdraw	✓	-	✓ (own)

On this page