PeopleHub Documentation

API Reference ​

Complete API documentation for PeopleHub services.

Interactive API Documentation ​

Each backend service has interactive API documentation at the /docs endpoint:

  • Main API: https://api.peoplehub.dev.wysbryxapp.com/docs
  • Candidate API: https://candidate-api.peoplehub.dev.wysbryxapp.com/docs
  • Integration API: https://integration-api.peoplehub.dev.wysbryxapp.com/docs
  • Notifications API: https://notifications-api.peoplehub.dev.wysbryxapp.com/docs

Format: OpenAPI/Swagger via Scalar UI Features: Interactive testing, request/response examples, schema validation

API Base URLs ​

Development:

  • Main API: https://api.peoplehub.dev.wysbryxapp.com
  • Candidate API: https://candidate-api.peoplehub.dev.wysbryxapp.com

Staging:

  • Main API: https://api.peoplehub.staging.wysbryxapp.com
  • Candidate API: https://candidate-api.peoplehub.staging.wysbryxapp.com

Production: Client-specific domains

Authentication ​

Method: JWT Bearer token in HTTP-only cookie

Endpoints:

  • Login: POST /api/auth/login
  • Refresh: POST /api/auth/refresh
  • Logout: POST /api/auth/logout

All protected endpoints require valid JWT token.

Common Endpoints (Main API) ​

Employees ​

  • GET /api/employees - List employees
  • GET /api/employees/:id - Get employee details
  • POST /api/employees - Create employee
  • PUT /api/employees/:id - Update employee
  • DELETE /api/employees/:id - Delete employee

Leave ​

  • GET /api/leave - List leave applications
  • POST /api/leave - Apply for leave
  • PUT /api/leave/:id/approve - Approve leave
  • PUT /api/leave/:id/reject - Reject leave

Performance ​

  • GET /api/performance/cycles - List performance cycles
  • GET /api/okr - List OKRs
  • POST /api/okr - Create OKR
  • PUT /api/okr/:id - Update OKR

Separation ​

  • POST /api/separation - Initiate separation
  • PUT /api/separation/:id/approve - Approve separation
  • GET /api/separation/:id/clearance - Get clearance status

Full documentation: Visit /docs endpoint on each API

Response Format ​

Success (200, 201):

json
{
  "data": { /* response data */ },
  "message": "Success"
}

Error (400, 401, 404, 500):

json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Detailed error message"
}

HTTP Status Codes ​

  • 200 OK: Successful GET request
  • 201 Created: Successful POST request
  • 400 Bad Request: Invalid input
  • 401 Unauthorized: Missing/invalid token
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server error

Pagination ​

List endpoints support pagination:

Query Parameters:

  • page: Page number (default: 1)
  • limit: Items per page (default: 20, max: 100)

Response:

json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Filtering & Sorting ​

Filtering: ?status=active&department=engineeringSorting: ?sortBy=createdAt&order=desc

Supported on most list endpoints.

Rate Limiting ​

Current: No explicit rate limits Planned: 1000 requests per minute per user (production)

API Versioning ​

Current: v1 (implicit, no version prefix) Future: /v2/ prefix for breaking changes

Data Model ​

Database Overview ​

Engine: PostgreSQL 17.5 Tables: 140+ tables Deployment: AWS RDS Multi-AZ ORM: Drizzle ORM (type-safe queries)

Core Entities ​

Users & Authentication:

  • user_master: User accounts and login credentials
  • role, permission, role_permission: RBAC system

Company & Organization:

  • company_master, customer_master, agency_master
  • data_group, master_data: Configuration data

Employees:

  • user_employment_details: Employment information
  • user_onboarding: Onboarding progress
  • project_allocation: Project assignments

Recruitment & Onboarding:

  • demand_master, demand_skill, employee_demand_status
  • Onboarding tables: Personal info, documents, BGV

Leave & Attendance:

  • Leave applications, balances, policies
  • Attendance logs, regularization requests

Performance:

  • performance_cycle, okr, okr_goal, sub_goal
  • okr_review, rating_scale

Separation:

  • separation_request, separation_approval
  • exit_survey_*, NOC tables

Skills & Certifications:

  • skill, skill_group, skill_cluster
  • certifications, certification_providers

Workflows:

  • request, request_approval, request_escalation_map

Notifications:

  • notification_definition, notification_template
  • notification_schedule

Support:

  • support_ticket, support_ticket_comment
  • support_ticket_attachment

Key Relationships ​

  • User → Employee: One-to-one
  • Employee → Manager: Self-referencing (reporting hierarchy)
  • Company → Departments: One-to-many
  • Employee → Projects: Many-to-many
  • Performance Cycle → OKRs → Goals: Hierarchical