Developers

Build on Mellow

Connect your tools to HR and payroll data across six countries — UK, Ireland, USA, UAE, India and Australia.

Get API keysDownload OpenAPI 3.1 →

REST · OpenAPI 3.1 · Bearer auth · Signed webhooks · Cursor pagination

Quick start

Your first employee list in 3 minutes

1

Create an account

Sign up at mellowhr.com/register — 14-day free trial, no credit card required.

2

Generate an API key

Go to Settings → API Keys. Pick the scopes you need — the form groups them by module.

3

Make your first call

Set the header Authorization: Bearer <your_key> and hit /api/v1/employees.

GET /api/v1/employees — your first call
curl -sS https://mellow-production.up.railway.app/api/v1/employees \
  -H "Authorization: Bearer sk_live_..."

The API in one minute

REST. Cursors. Bearer auth.

Base URL
https://mellow-production.up.railway.app/api/v1/
Authentication
Authorization: Bearer sk_live_…

Test keys use the sk_test_ prefix.

Rate limit
60 req/min per key. X-RateLimit-Limit, Remaining, Reset on every response. AI endpoints are 10 req/min.
Pagination
Cursor-based. Pass ?cursor=…&limit=25. Default 25, max 100.
Response envelope
{ "data": …, "pagination"?: {…}, "error"?: {…} }

Monetary values are integer minor units (pence, cents, fils) serialised as strings. Every response includes an X-Request-Id header.

Versioning
Every URL is prefixed with /api/v1/. We add backwards-compatible fields freely. Breaking changes get a new prefix with at least 12 months overlap.

Endpoint reference

Eleven module groups

The full machine-readable contract lives at /api/v1/openapi.json (OpenAPI 3.1). The summary below is the same surface, organised for humans.

Employees

Records, payslips and leave for a single employee.

  • GET/employeesList employees (cursor-paginated)
  • POST/employeesCreate an employee
  • GET/employees/{id}Retrieve one employee
  • PATCH/employees/{id}Update an employee
  • DELETE/employees/{id}Soft-delete an employee
  • GET/employees/{id}/payslipsPayslips for one employee
  • GET/employees/{id}/leaveLeave requests for one employee

Payroll

Pay runs end-to-end, plus BACS (UK) and WPS SIF (UAE) files.

  • GET/pay-runsList pay runs
  • POST/pay-runsCreate a pay run (country-aware)
  • GET/pay-runs/{id}Detail + pay lines
  • POST/pay-runs/{id}/calculateTrigger calculation
  • POST/pay-runs/{id}/approveApprove (payroll:admin)
  • GET/pay-runs/{id}/payslipsAll payslips for a run
  • GET/pay-runs/{id}/rti-statusRTI submission status (UK)
  • GET/pay-runs/{id}/bacsBACS Standard 18 file (UK, payroll-export:read)
  • GET/pay-runs/{id}/wpsWPS SIF v3 file (UAE, payroll-export:read)

Absence

Leave requests, balances, the team calendar and bank holidays.

  • GET/leaveList leave requests
  • POST/leaveCreate a leave request
  • PATCH/leave/{id}Approve / decline / cancel
  • GET/absence/balancesLeave balances per employee
  • GET/absence/calendarTeam absence calendar
  • GET/absence/bank-holidaysCountry-aware bank holidays

Compliance

DBS / professional checks, policies, right-to-work, alerts, deadlines.

  • GET/compliance/checksList compliance checks
  • GET/compliance/policiesList company policies
  • GET/compliance/rtwRight-to-work checks
  • GET/compliance/alertsActive compliance alerts
  • GET/compliance/deadlinesUpcoming deadlines

Onboarding

Active onboardings, complete tasks, list templates.

  • GET/onboardingActive onboardings + task counts
  • POST/onboarding/{id}/tasks/{taskId}/completeComplete a task
  • GET/onboarding/templatesList templates

Time & Attendance

Clock-in / clock-out and timesheets.

  • POST/time/clock-inClock an employee in
  • POST/time/clock-outClock an employee out
  • GET/time/timesheetsList timesheets

Performance

Review cycles and objectives.

  • GET/performance/reviewsList review cycles
  • GET/performance/objectivesList objectives

Recruitment

Vacancies and applications.

  • GET/recruitment/vacanciesList vacancies
  • GET/recruitment/applicationsList applications

Organisation

Current organisation, departments, locations.

  • GET/organisationCountry, currency, branding
  • GET/organisation/departmentsList departments
  • GET/organisation/locationsList locations (coming soon)

AI Agents

Query the agents — they answer questions and take actions (generate documents, run calculations, start workflows). POST /agents/query returns an answer, or an action result when the message asks the agent to do something.

  • GET/agentsList available agents
  • POST/agents/queryAsk a question or trigger an action

Pensions & RTI (UK)

Pension contributions and HMRC RTI submission history.

  • GET/pensionsList pension contributions
  • GET/rtiRTI submission history

Authentication & Scopes

Least privilege, always

Every API key carries a list of scopes. A scope isresource:action — actions are read, write, delete or admin. Granting payroll:admin implicitly grants payroll:read, :write and :delete. Exporting BACS/WPS payment files is a separate resource — payroll-export:read — so an approve key cannot pull decrypted bank details and an export key cannot approve a run; grant both only where one key must do both.

Employees

Employee records, payslips and leave for one employee.

  • Read employeesemployees:read
  • Create & update employeesemployees:write
  • Soft-delete employeesemployees:delete
  • Read payslipspayslips:read

Payroll

Pay runs, calculation, approval, BACS/WPS files.

  • Read pay runspayroll:read
  • Create & calculate pay runspayroll:write
  • Approve pay runspayroll:admin
  • Export BACS/WPS payment files (decrypts bank details)payroll-export:read
  • Read RTI status (UK)rti:read

Absence

Leave requests, balances, team calendar, bank holidays.

  • Read absence + balancesabsence:read
  • Create leave requestsabsence:write
  • Approve / decline leaveabsence:admin
  • Read leave (legacy)leave:read
  • Create leave (legacy)leave:write
  • Delete leave (legacy)leave:delete

Compliance

Compliance checks, policies, right-to-work, alerts, deadlines.

  • Read compliance datacompliance:read
  • Acknowledge / resolve alertscompliance:write

Time & Attendance

Clock-in / clock-out, timesheets.

  • Read timesheets & entriestime:read
  • Clock in / outtime:write

Performance

Review cycles and objectives.

  • Read reviews & objectivesperformance:read
  • Update objectivesperformance:write

Recruitment

Vacancies and applications.

  • Read vacancies & applicationsrecruitment:read
  • Update vacanciesrecruitment:write

Organisation

Org details, departments, locations.

  • Read organisationorganisation:read

Pensions

Pension scheme and contributions.

  • Read pensionspensions:read

AI Agents

Query Mellow AI agents — the Employee Assistant and specialists.

  • Query agentsagents:read
  • Query the Employee Assistant (legacy)ai:read

Webhooks

Register, rotate and revoke outbound webhook endpoints.

  • Manage webhook endpointswebhooks:admin

Practice

Cross-client management for payroll bureaus & HR practices (key must belong to a practice).

  • Read practice + clientspractice:read
  • Add clientspractice:write
  • Manage the practicepractice:admin

Security checklist

  • Store keys in your platform's secret manager. Never commit them. Never send them to a browser.
  • Create one key per integration, with the minimum scopes that integration needs.
  • Rotate keys every 90 days: mint a new key, swap it in, then revoke the old one from Settings → API Keys.
  • Set expires_at on keys for short-lived integrations. Expired keys reject as 401.
  • Trust the X-Request-Id header — quote it in support tickets and we can find the exact request in our logs.

Outbound webhooks

Signed events you can trust

Register an endpoint URL and a list of event types. Every delivery is signed with HMAC-SHA256 — verify it before you trust the body.

Event catalogue

Sixteen events across the public-API surface. Subscribe via the API (programmatic webhook endpoint registration is available via the kit's createWebhookEndpoint helper — a dashboard UI ships next).

  • employee.createdFires after a new employee is created via the API.
  • employee.updatedFires after PATCH /employees/{id}.
  • employee.departedFires after DELETE /employees/{id} (soft delete).
  • payrun.createdFires after POST /pay-runs.
  • payrun.calculatedFires after POST /pay-runs/{id}/calculate finishes (REVIEW status).
  • payrun.approvedFires after POST /pay-runs/{id}/approve.
  • payrun.submittedFires after a UK pay run is marked submitted to HMRC (RTI).
  • payslip.approvedFires when an individual payslip is approved.
  • leave.requestedFires after POST /leave.
  • leave.approvedFires when a leave request is approved.
  • leave.declinedFires when a leave request is declined.
  • leave.rejectedLegacy alias of leave.declined — kept for older subscribers.
  • compliance.alert.createdFires when a new compliance alert is raised.
  • onboarding.startedFires when an onboarding template is applied to a new starter.
  • onboarding.completedFires when the final outstanding onboarding task is completed.
  • rti.submittedFires after an RTI FPS / EPS is accepted by HMRC.
Verify a Saltcore-Signature header
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyMellowWebhook(rawBody, signatureHeader, secret) {
  // Header: "Saltcore-Signature: t=<unix>,v1=<hex_hmac>"
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("="))
  );
  const expected = createHmac("sha256", secret)
    .update(parts.t + "." + rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}
Retry behaviour: deliveries that fail get a single retry today; the dead-letter queue and exponential backoff ship with the durable worker (next session). Every attempt is recorded — quote the event id when you reach out.

One API, six countries

Responses adapt to the organisation's country

GET /api/v1/organisation always returns the country and currency. Country-specific routes 404 cleanly when they don't apply — e.g. /pay-runs/{id}/bacs is UK-only; /pay-runs/{id}/wps is UAE-only; /pay-runs/{id}/rti-status is UK-only.

UK organisation
{
  "data": {
    "id": "org_uk_1",
    "name": "Acme Ltd",
    "country_code": "GB",
    "region_code": null,
    "currency_code": "GBP",
    "subscription_tier": "professional",
    ...
  }
}
UAE organisation
{
  "data": {
    "id": "org_uae_1",
    "name": "Acme FZ-LLC",
    "country_code": "AE",
    "region_code": "DXB",
    "currency_code": "AED",
    "subscription_tier": "professional",
    ...
  }
}

United Kingdom

NI number on file, tax code, RTI status, BACS file

Ireland

PRSI class, USC bands, Revenue ROS submission notes

United States

FICA breakdown, federal + state tax, Form 941 quarter

United Arab Emirates

WPS SIF file, end-of-service gratuity, UAE-national-only social insurance

India

TDS, PF, ESI, professional tax (state-specific), old vs new regime

Australia

Superannuation, HECS-HELP, Medicare levy, STP-ready payload

SDKs

Typed clients — coming soon

While we polish the generated clients, the OpenAPI spec at /api/v1/openapi.json is the canonical source — point any OpenAPI code generator at it.

@saltcore-sdk/mellow — TypeScript

Generated from the OpenAPI spec. Full type safety, ESM + CJS, Node 18+.

Coming soon

mellow-python — Python

Generated from the OpenAPI spec. Async + sync clients, type hints, 3.10+.

Coming soon

Build something useful.

Questions? Bug reports? Ideas for the next endpoint? hello@mellowhr.com.

Get API keys/api/v1/openapi.json