Developer docs
Overview
REST · JSON · API keys

AltomateHR API

Read and write a company's HR and payroll data from your own system: employees, projects, claims, leave, attendance, overtime and payroll runs. Every request acts inside one company, with the permissions its API key was given.

Authentication

A company's admin creates an API key in AltomateHR. A key starts with wp_live_, belongs to one company, and is shown only once. Send it as a bearer token on every request: 

curl https://<api-host>/whoami \
  -H "Authorization: Bearer wp_live_xxx"
  • Every call is limited to the key's own company. There is no way to read or change another company's data with it.
  • A key acts with admin rights in that company, narrowed by its scopes.
  • An unknown or revoked key, or one whose company no longer exists, gets 401. The response doesn't say which, deliberately.
  • Some endpoints are for people only and answer 403 to any key: a person's own actions (clocking in, applying for leave, filing a claim or overtime, notifications), account actions (passwords, switching company) and platform settings (managing API keys and admin access, the activity log, accounting connections).
  • Every other endpoint needs a scope, listed on its page. Only GET /whoami and GET /pending work with any key.
Treat a key like a password: keep it on your server, never in a browser or app bundle. If one leaks, revoke it in AltomateHR and create a new one.

Scopes

A key carries a set of scopes chosen when it's created. Each endpoint page lists the scope it needs; a key without it gets 403 with Caller is missing required scope: ….

AreaReadWrite
Employeesemployees:reademployees:write
Claimsclaims:readclaims:write
Leaveleave:readleave:write
Attendanceattendance:readattendance:write
Overtimeovertime:readovertime:write
Projectsprojects:readprojects:write
Teamsteams:readteams:write
Accounts (chart of accounts)accounts:readaccounts:write
Policiespolicies:readpolicies:write
Organizationorganizations:readorganizations:write
Payrollpayroll:readpayroll:write
Notifications—notifications:write
Single sign-on hand-off—sso:write

payroll:write covers creating and running payroll, adjustments, submitting, approving, rejecting and reverting runs, and payroll settings. A payroll run is money leaving a company, so only grant it to a system that needs it.

Some areas are also part of a company's plan. If the plan doesn't include a module, its endpoints answer 403 with This organization's plan does not include the '…' module., whatever the key's scopes.

Errors

Errors come back as JSON in one of three shapes. Read the status code first.

StatusWhenBody
400A field failed validation{ "errors": { "Field": ["message"] } }
400 / 409The request is valid but not allowed now (e.g. a run that's no longer a draft, a month that already has a run){ "error": "message" }
401Missing, unknown or revoked keyempty
403Missing scope, module not in the plan, or a people-only endpoint{ "error": { "status": 403, "message": "…" } }
404Not found in this companyempty or { "error": "…" }

A robust client reads error when it's a string, error.message when it's an object, and the first entry of errors otherwise.

Conventions

  • JSON request and response bodies, with camelCase field names. Send Content-Type: application/json.
  • Ids are strings. Employees have two: the user id (from /employees) and the payroll profile id (employeeProfileId, from /payroll/employees). Payroll endpoints take the profile id; each endpoint page says which one it needs.
  • Enums are strings, such as "DRAFT" or "MONTHLY".
  • Money is a number with two decimal places, in Malaysian ringgit.
  • Dates are ISO 8601. A payroll month is given as periodYear + periodMonth (1–12).
  • Rate limits: none on API-key requests today. Keep calls sequential for writes to the same payroll run.

Check a key

GET /whoami No scope needed

What the key is and what it may do. Use it to confirm a pasted key belongs to the company you expect before storing it.

Response 200

FieldTypeMeaning
organizationIdstringThe company the key belongs to.
apiKeyIdstringThe key's id.
tokenNamestringThe label the key was given in AltomateHR.
rolestringAlways "Admin" for a key.
scopesstring[]The key's scopes, sorted.
featuresstring[]Optional capabilities this deployment supports. Check here before sending an optional field your integration added later.
 
{
  "organizationId": "org_123",
  "apiKeyId": "key_123",
  "tokenName": "Payroll converter",
  "role": "Admin",
  "scopes": ["employees:read", "payroll:read", "payroll:write"],
  "features": ["onboarding.bulk", "sso.inbound"]
}

401 when the key is unknown, revoked, or its company no longer exists.