Skip to content
emploreadocs

REST API reference

Base URL https://app.emplorea.com/api/v1. The complete machine-readable contract lives in the OpenAPI 3.1 spec at /openapi.json (YAML at /openapi.yaml, interactive reference at /docs/api-reference). Every endpoint carries an x-agent-hints extension explaining its agent use case.

Endpoints

GET    /company                     company context - call this first
PATCH  /company                     update name/website/industry/phone (admin scope)

GET    /employees                   ?status=active|terminated|all &department &page &limit
POST   /employees                   create (first_name, last_name, email,
                                    employment_type, start_date, jurisdiction, role)
GET    /employees/:id
PATCH  /employees/:id               update editable fields
DELETE /employees/:id               terminate (records kept - soft delete);
                                    optional body {termination_date, termination_reason}

GET    /leave                       ?employee_id &status &from &to - pending first
POST   /leave                       request; returns non-blocking warnings
GET    /leave/:id
PATCH  /leave/:id/approve
PATCH  /leave/:id/decline           body {reason} - required
DELETE /leave/:id                   cancel; optional body {reason}
GET    /leave/balances              ?employee_id - annual + sick per person

GET    /leave-types                 ids + rules for POST /leave
GET    /public-holidays             ?jurisdiction=AU|NZ|UK &region &year

GET    /webhooks                    webhooks scope
POST   /webhooks                    {url (https), events[]} - secret returned once
DELETE /webhooks/:id

Coming soon (501 + x-status "coming-soon" in the spec):
/documents · /compliance · /ask-hr · /jobs

Common workflows

  • Onboard a hire: GET /company, then POST /employees - the person appears on the dashboard immediately.
  • Book leave: GET /leave-types, GET /leave/balances?employee_id=..., POST /leave, read the warnings array.
  • Clear approvals: GET /leave?status=pending, then approve or decline each id.
  • Audit a team: GET /employees?status=all plus GET /leave?from=...&to=... for the period.

Errors and limits

401 {"error":{"code":"UNAUTHORISED","message":"..."}}   missing/invalid key
403 {"error":{"code":"FORBIDDEN","message":"..."}}      key lacks the scope
404 {"error":{"code":"NOT_FOUND","message":"..."}}      wrong id or wrong company
400 {"error":{"code":"VALIDATION_ERROR","field":"..."}} fix the named field
409 {"error":{"code":"CONFLICT","message":"..."}}       duplicate or wrong state
429 {"error":{"code":"RATE_LIMITED","message":"..."}}   100 req/min per key

Example - JavaScript

// EMPLOREA_KEY comes from your secret store or environment
const response = await fetch("https://app.emplorea.com/api/v1/employees", {
  headers: { Authorization: `Bearer ${EMPLOREA_KEY}` },
});
const { data, meta } = await response.json();

Example - Python

import os, requests

response = requests.get(
    "https://app.emplorea.com/api/v1/leave/balances",
    headers={"Authorization": f"Bearer {os.environ['EMPLOREA_KEY']}"},
)
balances = response.json()["data"]