API Documentation

Overview

Third-party integrations authenticate as an API User — a dedicated credential set created and managed by an Octal HR administrator. API Users carry a scoped role that determines exactly which modules and operations are accessible.

Base URL

All v1 API requests are prefixed with:

https://api.octalhr.com/v1/

All endpoints accept and return application/json. Include the following headers on every authenticated request:

Content-Type: application/json
Accept: application/json
Authorization: Bearer <access_token>

All list endpoints support pagination via ?page=1&per_page=25 query parameters. Responses include a meta object with total, page, per_page, and last_page.

Authentication

Every protected endpoint requires a valid JWT access token in the Authorization: Bearer header. Tokens are valid for 1 hour. Use the refresh endpoint to obtain a new pair without re-posting credentials.

On success, every auth endpoint returns the same token envelope:

{
  "success": true,
  "data": {
    "access_token":  "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh_token": "a3f9d2e1c8b...",
    "token_type":    "Bearer",
    "expires_in":    3600
  }
}

POST /api/v1/auth/token

Exchanges an API Key + API Secret for a JWT pair. The API User must be created and activated by an admin — see Creating API Users.

Request Body

{
  "api_key":    "hrms_4a7f2e9d1c3b8a6e...",   // required
  "api_secret": "9d3f1a7c2e8b4d6a..."    // required — shown once at creation
}

Success Response 200

{
  "success": true,
  "data": {
    "access_token":  "eyJ...",
    "refresh_token": "c9e2...",
    "token_type":    "Bearer",
    "expires_in":    3600,
    "api_user": { "id": 1, "name": "ERP Connector" },
    "tenant":   { "id": 4 }
  }
}

POST /api/v1/auth/refresh

Exchanges a valid refresh token for a new access + refresh token pair. The old refresh token is immediately revoked (token rotation). Refresh tokens expire after 30 days of inactivity.

{
  "refresh_token": "a3f9d2e1c8b..."   // required
}

Returns the same token envelope as /auth/token.

POST /api/v1/auth/logout 🔒 Auth required

Revokes the provided refresh token. The current access token remains valid until its natural expiry (max 1 hour). Call this when your integration session ends.

{
  "refresh_token": "a3f9d2e1c8b..."
}

Returns 200 with "message": "Logged out successfully." even if the token was already revoked.

Full CRUD for employee records including termination, reinstatement, and sub-resources like documents, bank accounts, and emergency contacts.

Example — List active employees

GET /v1/hr/employees?status=active&per_page=50
Authorization: Bearer eyJ...

{
  "success": true,
  "data": [
    {
      "id": 42,
      "employee_code": "EMP-0042",
      "full_name": "Sara Khan",
      "email": "sara.khan@company.com",
      "department": "Finance",
      "designation": "Senior Accountant",
      "hire_date": "2022-03-01",
      "status": "active"
    }
  ],
  "meta": { "total": 84, "page": 1, "per_page": 50, "last_page": 2 }
}

CRUD for structured profile sections: work history, education, skills, dependants, certifications, and distinctions. All routes are nested under /employees/{id}/.

Key fields — work-history POST body

{
  "company_name":       "Acme Corp",       // required
  "designation":        "Team Lead",
  "department":         "Engineering",
  "from_date":          "2019-01-01",       // required
  "to_date":            "2022-12-31",
  "responsibilities":   "Led a team of 6...",
  "reason_for_leaving": "Better opportunity",
  "last_salary":        120000,
  "reference_name":     "Jane Doe",
  "reference_contact":  "+1-555-000-1234"
}

Read-only org chart endpoints. Returns the reporting hierarchy as a nested tree, or a flat node for a single employee.

Attendance records track daily check-in/check-out events per employee. Filter by ?employee_id=42&from=2026-05-01&to=2026-05-31.

LOP records are deducted from the employee's payslip for the applicable period.

Allocate leave entitlements to employees or groups for a specific leave type and period.

Example response — employee balances

{
  "success": true,
  "data": [
    { "leave_type": "Annual",  "allocated": 21, "used": 5, "balance": 16 },
    { "leave_type": "Sick",    "allocated": 10, "used": 2, "balance": 8  },
    { "leave_type": "Casual",  "allocated": 7,  "used": 0, "balance": 7  }
  ]
}

Salary structures define the components (basic, HRA, allowances, deductions) that make up an employee's pay package.

A payroll run processes salaries for a given period. Runs go through draft → processed → approved → finalized states.

One-off additions or deductions applied to a specific payroll run (bonuses, penalties, reimbursements).

Tenant-level wage settings — minimum wage, overtime multipliers, and currency configuration used in payroll calculations.

Short-term salary advances paid to employees ahead of their pay date. Recovered automatically from the next payslip.

Arrears are supplementary amounts added to a payroll run to cover under-payments from previous periods.

Configure multi-level approval chains for payroll runs. Each level defines a role that must approve before the run advances.

Employee loan management with EMI, bullet, or manual repayment schedules. Loans integrate with payroll for automatic EMI deductions.

Loan — POST body

{
  "employee_id":    42,              // required
  "loan_type_id":   2,
  "amount":         500000,          // required
  "repayment_type": "emi",           // emi | bullet | manual
  "emi_months":     12,
  "interest_rate":  0,               // percent per annum
  "start_date":     "2026-06-01"
}

Tax regimes define the slab structure applied during payslip tax computation. Multiple regimes can exist simultaneously (e.g., different fiscal years).

Company bank accounts used for salary disbursement and payment vouchers.

Visitor management — log walk-in visits, manage a blacklist, and issue visitor badges.

Tenant-level settings: company name, locale, currency, logo, payroll period, etc.

Loss-of-pay deduction rules per absence type, applied automatically in payroll calculation.

Read-only audit trail of all create/update/delete actions across the system. Filter by ?user_id=5&module=payroll&from=2026-05-01.

Permission Slugs

Every endpoint is gated by a permission slug. Assign slugs to a role in Settings → Roles & Permissions, then assign that role to an API User. The table below lists all slugs available for API Users (marked is_api = 1 in the system).

HR

Attendance

Leave

Payroll

Loans

Tax

Other Modules

Settings & Logs

Error Codes

All errors follow a consistent envelope:

{
  "success": false,
  "errors": [
    {
      "field":   "email",           // null for non-field errors
      "message": "Email is required."
    }
  ]
}

Creating API Users

Third-party systems authenticate as an API User — a dedicated credential set with its own scoped role. API Users are created by an administrator in the Octal HR panel. The API Secret is shown exactly once at creation — store it immediately.

Typical Integration Pattern

# 1. Authenticate once per session (token valid for 1 hour)
import requests, os

resp = requests.post("https://api.octalhr.com/v1/auth/token", json={
    "api_key":    os.environ["OCTALHR_API_KEY"],
    "api_secret": os.environ["OCTALHR_API_SECRET"],
})
token = resp.json()["data"]["access_token"]
headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}

# 2. Use the token on subsequent requests
employees = requests.get(
    "https://api.octalhr.com/v1/hr/employees?status=active",
    headers=headers
).json()

# 3. Refresh before expiry (or handle 401 → re-auth)
refresh_resp = requests.post(
    "https://api.octalhr.com/v1/auth/refresh",
    json={"refresh_token": resp.json()["data"]["refresh_token"]}
)
token = refresh_resp.json()["data"]["access_token"]