Employees

Everyone in the organization, with their role and employment basics.

Response 200

curl https://<api-host>/employees \
  -H "Authorization: Bearer wp_live_xxx"

Add a member to the key's own organization. If the email already belongs to a user (someone who works at another company on AltomateHR too), that identity is reused — a second membership is added to it — rather than a new account created.

Request

Response 200

The new (or reused) member, in the same shape as a row from GET /employees.

Errors

curl -X POST https://<api-host>/employees \
  -H "Authorization: Bearer wp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Example",
    "dateOfBirth": "1992-04-10",
    "employeeNumber": "EMP-042",
    "role": "Employee"
  }'

Change a member's role, supervisor-layer placement, or roster basics. {id} is the user id.

Request

Response 200

The updated member, in the same shape as a row from GET /employees.

Errors

curl -X PUT https://<api-host>/employees/usr_123 \
  -H "Authorization: Bearer wp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "role": "Supervisor", "jobTitle": "Site Lead" }'

{id} is the user id (as returned by GET /employees).

Response 200

If no profile has ever been saved for this person, the response is a shell with only id/employeeProfileId (null)/email/name populated and every other field at its default — so a form can still load.

Every other field below is editable — see PUT /employees/{id}/profile.

Create (on first save) or replace this person's profile. {id} is the user id.

Request

Context fields (id, employeeProfileId, email, name) are ignored if sent — they come from the route and the user record. Everything else:

Personal / demographic

Employment placement

Spouse / tax relief

[
  {
    "abilityStatus": "NORMAL",
    "currentlyStudying": "UNDER_18",
    "pcbDeduction": "NONE"
  }
]

Prior-employment year-to-date (for tax)

EPF

SOCSO / EIS / SKBBK

Income tax

Bank / payment

Salary & salary-change trail

[
  {
    "category": "allowance_standard",
    "name": "Transport",
    "amount": 300.00,
    "treatAsRecurring": false
  }
]

Payroll config

Lifecycle (archiving)

Response

200 with the full profile (same shape as GET) on success.

Errors

curl -X PUT https://<api-host>/employees/usr_123/profile \
  -H "Authorization: Bearer wp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "idNumber": "900101-14-5567",
    "idType": "NRIC",
    "maritalStatus": "MARRIED",
    "salaryType": "MONTHLY",
    "monthlySalary": 5000.00,
    "contributeToEpf": true,
    "contributeToEis": true,
    "paymentMethod": "BANK_TRANSFER"
  }'

Response 200

404 (empty) when {id} is not a member of this organization.

multipart/form-data with one field, file. Up to 10 MB.

Response 200

The new document, in the same shape as a GET /employees/{id}/documents row.

Errors

curl -X POST https://<api-host>/employees/usr_123/documents \
  -H "Authorization: Bearer wp_live_xxx" \
  -F "file=@contract.pdf"

Streams the file bytes with its original content type. 404 (empty) if either id doesn't resolve.

204 on success. 404 (empty) if either id doesn't resolve.

Which of the 5 forms can be generated right now, and why not when they can't.

Response 200

404 (empty) when {id} is not a member of this organization.

{
  "kind": "CP22",
  "code": "CP22",
  "title": "New-employee notification",
  "description": "Notification to LHDN that a new employee has joined.",
  "needsYearPicker": false,
  "enabled": true,
  "disabledReason": null,
  "badge": "Due in 18 days",
  "badgeVariant": "success"
}

Request

Response 200

application/pdf bytes.

Errors

curl https://<api-host>/employees/usr_123/lhdn-forms/CP22/download \
  -H "Authorization: Bearer wp_live_xxx" \
  -o CP22_EMP-042.pdf

Request

Response 200

The file bytes, as xlsx or csv content type (see Importing & exporting below for the exact MIME types). The XLSX template includes a READ ME sheet and a Columns guide alongside the empty Employees sheet; a key without Payroll access in its org gets a template without the statutory/salary/bank columns.

curl https://<api-host>/employees/import/template?format=xlsx \
  -H "Authorization: Bearer wp_live_xxx" \
  -o employees-import-template.xlsx

The whole roster, in the import's column layout — edit it and re-import to bulk-update.

Request

Response 200

File bytes, same content type as the template:

400 { "error": "Choose at least one field to export." } when fields is set but none of the keys are recognised or allowed.

curl "https://<api-host>/employees/export?format=csv" \
  -H "Authorization: Bearer wp_live_xxx" \
  -o employees.csv

The column keys GET /employees/export?fields=… accepts, grouped for a picker UI.

Response 200

The response is a flat array (not grouped); statutory/salary/bank keys are omitted for a key without Payroll access in its org.

multipart/form-data. Field file: a .csv or .xlsx export/template, detected by extension.

Request

Key columns (by header text or listed alias)

Every other profile column from PUT /employees/{id}/profile has a matching sheet column (see GET /employees/export/fields for the full, grouped list) — dates as YYYY-MM-DD, booleans as Yes/No, percentages as plain numbers, money tolerant of formatting like "RM 5,000.00". Statutory/salary/bank columns are only in the file for a key whose org grants Payroll access; present in an uploaded file without that access, they're ignored (not an error).

Response 200

Errors

curl -X POST https://<api-host>/employees/import \
  -H "Authorization: Bearer wp_live_xxx" \
  -F "file=@employees.xlsx" \
  -F "blankCells=Keep"

{
  "ok": false,
  "created": 1,
  "updated": 4,
  "errors": [
    {
      "row": 7,
      "message": "\"missing@example.com\" is new, so Employee No is required."
    }
  ],
  "warnings": [],
  "createdAccounts": [
    {
      "email": "new.hire@example.com",
      "name": "New Hire",
      "password": "new.hire@example.com1123"
    }
  ]
}

One number — seats for billing — rather than a list. Counts memberships, not users: the same person in two of your organizations counts once per organization.

Response 200

{ "count": 42, "asOf": "2026-01-15T03:21:09.4130000Z" }

curl https://<api-host>/employees/active-count \
  -H "Authorization: Bearer wp_live_xxx"

What's waiting for a decision, across claims and leave (not employees specifically — there's nothing "pending" on a roster row). A key only sees the sections its scopes allow; the rest are named in omitted rather than reported as zero, so an empty queue and "you may not ask" are never confused.

Response 200

{ "claims": 3, "omitted": ["leave"] }

curl https://<api-host>/pending \
  -H "Authorization: Bearer wp_live_xxx"