Reference

# CubeHR API documentation

The full REST reference: 29 modules and 305 endpoints. Everything the CubeHR app does, your own systems can do too.

Base URL

`https://api.cube-hr.co.uk/api/v1`
## JWT authentication

For user-facing web and mobile apps.

`Authorization: Bearer <token>`
## API key authentication

For server-to-server integrations.

`X-API-Key: <api_key>`
## Modules

- [13 endpointsAuthenticationJWT authentication, MFA setup, password management, and session control.](/docs/authentication)
- [18 endpointsEmployeesEmployee records, org chart, change history, offboarding, and emergency contacts.](/docs/employees)
- [10 endpointsDepartments & TeamsDepartment and team structure management.](/docs/departments)
- [10 endpointsJob TitlesJob title definitions, salary banding, and employee job assignments.](/docs/jobs)
- [12 endpointsLocations & Working PatternsOffice locations and working pattern configurations.](/docs/locations)
- [22 endpointsLeave ManagementLeave types, employee balances, requests, approvals, and carry-over management.](/docs/leave)
- [7 endpointsAbsence ManagementSickness tracking, Bradford Factor calculation, and absence statistics.](/docs/absences)
- [12 endpointsCalendar & HolidaysCalendar events, iCal subscriptions, public holidays, and company holiday management.](/docs/calendar)
- [37 endpointsPerformanceObjectives, milestones, performance reviews, 360° feedback, and 1-to-1 meetings.](/docs/performance)
- [4 endpointsSettingsHierarchical company settings with audit history.](/docs/settings)
- [5 endpointsSalariesEmployee salary history, current salary, and salary management.](/docs/salaries)
- [19 endpointsUsers & AccessUser accounts, roles, user groups, and RBAC permissions.](/docs/users)
- [21 endpointsAsset TrackingAsset lifecycle tracking: categories, assignments, maintenance and notes.](/docs/assets)
- [14 endpointsReports & DashboardsHeadcount reports, leave liability, asset reports, and role-specific dashboards.](/docs/reports)
- [13 endpointsSocial & EventsCompany social feed, posts, reactions, comments, and social events.](/docs/social)
- [13 endpointsRecruitmentJob postings, candidates and CVs, the hiring pipeline, and converting a hire into an employee.](/docs/recruitment)
- [19 endpointsDocumentsEmployee and company document management, uploads, folder templates.](/docs/documents)
- [9 endpointsAPI KeysAPI key creation, management, permissions, and usage logs.](/docs/api-keys)
- [5 endpointsNotificationsIn-app notifications and real-time SSE notification stream.](/docs/notifications)
- [3 endpointsPresenceReal-time user presence status and SSE presence stream.](/docs/presence)
- [4 endpointsPay GradesPay grade banding structures for salary ranges.](/docs/pay-grades)
- [4 endpointsCost CentresCost centre definitions for financial reporting.](/docs/cost-centres)
- [6 endpointsCustom FieldsCustom field definitions and employee custom field values.](/docs/custom-fields)
- [4 endpointsApproval ChainsMulti-step leave approval chain configuration.](/docs/approval-chains)
- [4 endpointsBlackout DatesLeave blackout periods when bookings are restricted.](/docs/blackout-dates)
- [3 endpointsCompanyCompany branding, structure, and subsidiary management.](/docs/company)
- [6 endpointsEmployee TemplatesOnboarding checklist templates for new employees.](/docs/employee-templates)
- [5 endpointsMigrationBreatheHR data migration tools: validate, preview and run.](/docs/migration)
- [3 endpointsReference DataCountries, timezones, and currencies reference data.](/docs/reference)

## Response format

Success

jsonCopy`{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "pages": 8
  }
}`Error

jsonCopy`{
  "success": false,
  "error": "Not found",
  "code": "EMPLOYEE_NOT_FOUND",
  "errors": {
    "email": "Invalid email"
  }
}`
## HTTP status codes

| Code | Meaning | When you will see it |
| --- | --- | --- |
| 200 | OK | Successful GET, PUT or PATCH |
| 201 | Created | Successful POST, resource created |
| 400 | Bad request | Validation error |
| 401 | Unauthorised | Missing or invalid credentials |
| 403 | Forbidden | Authenticated but not permitted |
| 404 | Not found | Resource does not exist |
| 422 | Unprocessable | Business logic error |

---

**URL:** https://cube-hr.co.uk/docs