Update an employee

PATCH

/employees/{id}

const url = 'https://api.usepayloom.com/api/v1/employees/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"jurisdiction":"GH","full_name":"example","title":"example","first_name":"example","middle_name":"example","last_name":"example","suffix":"example","classification":"employee","denomination_currency":"example","payment_currency":"example","staff_id":"example","start_date":"2026-04-15","end_date":"2026-04-15","birthdate":"2026-04-15","phone":"example","department_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","position_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","location_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","hod_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","tax_profile":{},"household_composition":{},"bank_details":{},"statutory_ids":{"ghana_card_pin":"GHA-573620486-0"},"compensation":[{"component_code":"basic","amount_cents":1,"effective_from":"2026-04-15","proratable":true}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://api.usepayloom.com/api/v1/employees/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "jurisdiction": "GH", "full_name": "example", "title": "example", "first_name": "example", "middle_name": "example", "last_name": "example", "suffix": "example", "classification": "employee", "denomination_currency": "example", "payment_currency": "example", "staff_id": "example", "start_date": "2026-04-15", "end_date": "2026-04-15", "birthdate": "2026-04-15", "phone": "example", "department_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "position_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "location_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "hod_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "tax_profile": {}, "household_composition": {}, "bank_details": {}, "statutory_ids": { "ghana_card_pin": "GHA-573620486-0" }, "compensation": [ { "component_code": "basic", "amount_cents": 1, "effective_from": "2026-04-15", "proratable": true } ] }'

Omitted fields are left untouched. jurisdiction and denomination_currency cannot be changed — mid-history changes to either are a migration, not an edit.

Compensation entries CLOSE AND APPEND: a new entry closes the currently open row for that component at its effective_from and adds a new one. The prior amount is never rewritten, so payslips already priced against it still reproduce exactly. effective_from must be after the open row’s.

Authorizations

ApiKey

Parameters

Path Parameters

required

string format: uuid

Header Parameters

Idempotency-Key

string

<= 255 characters

A client-generated unique string (a UUID works). Retrying with the same key and body replays the original response instead of acting twice.

Request Body^required

application/json

Statutory inputs (tax_profile, household_composition), statutory identifiers (statutory_ids) and payment details (bank_details) may be WRITTEN but are never read back — see the Employee schema.

object

jurisdiction

Required on create; immutable afterwards.

string

Example

GH

full_name

A whole name, split server-side into the parts below. Convenience only: when any part is sent alongside it, the parts win and this is ignored.

string

title

string

first_name

Required on create; a name must have both parts.

string

middle_name

string

last_name

Required on create; a name must have both parts.

string

suffix

string

classification

string

Allowed values: employee contractor

denomination_currency

Required on create; immutable afterwards.

string

payment_currency

Defaults to the denomination currency.

string

staff_id

string

start_date

string format: date

end_date

string format: date

birthdate

Drives age-banded contributions (e.g. Singapore CPF).

string format: date

phone

Normalized to E.164 server-side; the submitted format is not trusted.

string

department_id

string format: uuid

position_id

string format: uuid

location_id

string format: uuid

hod_id

string format: uuid

tax_profile

object

key

additional properties

any

household_composition

object

key

additional properties

any

bank_details

The payee’s account, keyed by what the country uses (iban, clabe, nuban + bank_code, routing_number + account_number, sort_code, institution_number + transit_number, or the mobile-money triple). Write-only. Where the identifier carries a check digit (IBAN, CLABE, NUBAN, ABA routing number) it is verified on write and a failure is a 422: an account that fails its own arithmetic cannot exist, and the payment would bounce after payday. The check is arithmetic only and says nothing about whose account it is.

object

key

additional properties

any

statutory_ids

Statutory personal identifiers keyed by the jurisdiction’s catalog (e.g. ghana_card_pin, kra_pin, nin, rsa_pin, nric_fin). Values are normalized and format-checked server-side; the entry that is the person’s tax identifier feeds the statutory filings. A key the jurisdiction does not define is stored untouched.

object

key

additional properties

any

Example

{
  "ghana_card_pin": "GHA-573620486-0"
}

compensation

Array<object>

object

component_code

required

string

Example

basic

amount_cents

required

Minor units of the employee’s denomination currency.

integer

effective_from

Required when changing existing compensation; must be after the open row’s start.

string format: date

proratable

boolean

default: true

Responses

200

application/json

Statutory inputs (tax profile, household composition, birthdate) and PII (tax identifier, phone, bank details) are deliberately not exposed.

object

string format: uuid

object

string

Allowed value: employee

staff_id

Your own identifier for this person.

string

nullable

full_name

Derived from first_name, middle_name, last_name and suffix. The name printed on payslips and carried in bank payment files; the honorific is not included.

string

title

Honorific (Mr

string

nullable

first_name

string

middle_name

string

nullable

last_name

Null only on a legacy one-word name.

string

nullable

suffix

Jr., III, PhD … Part of the legal name.

string

nullable

classification

string

Allowed values: employee contractor

jurisdiction

string

denomination_currency

string

payment_currency

string

start_date

string format: date

nullable

end_date

string format: date

nullable

archived

boolean

bank_name_check

Whether the account on file was confirmed to belong to this employee, asked of the payment partner before payday. close is a name a person would recognise as the same person and is paid; mismatch is not paid from a funded balance until someone with funding.manage acknowledges it; unavailable means the rail answers no name enquiry. Null when it has never been asked. The name the BANK holds is deliberately not exposed.

string

nullable

Allowed values: matched close mismatch unavailable

bank_name_checked_at

string format: date-time

nullable

department

string

nullable

position

string

nullable

location

string

nullable

created_at

string format: date-time

updated_at

string format: date-time

Example

{
  "object": "employee",
  "classification": "employee",
  "jurisdiction": "GH",
  "bank_name_check": "matched"
}

401

Missing, invalid, revoked or expired key.

application/json

object

error

object

code

required

string

Allowed values: missing_token invalid_token revoked expired insufficient_scope organization_not_operable not_found invalid_request validation_failed rate_limited

message

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "missing_token"
  }
}

403

The key is valid but lacks the required scope.

application/json

object

error

object

code

required

string

Allowed values: missing_token invalid_token revoked expired insufficient_scope organization_not_operable not_found invalid_request validation_failed rate_limited

message

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "missing_token"
  }
}

404

No such resource in this organization.

application/json

object

error

object

code

required

string

Allowed values: missing_token invalid_token revoked expired insufficient_scope organization_not_operable not_found invalid_request validation_failed rate_limited

message

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "missing_token"
  }
}

409

A request with this Idempotency-Key is still in progress.

application/json

object

error

object

code

required

string

Allowed values: missing_token invalid_token revoked expired insufficient_scope organization_not_operable not_found invalid_request validation_failed rate_limited

message

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "missing_token"
  }
}

Headers

Retry-After

integer

422

Validation failed, or the Idempotency-Key was reused for a different request (idempotency_key_reuse).

application/json

object

error

object

code

required

string

Allowed values: missing_token invalid_token revoked expired insufficient_scope organization_not_operable not_found invalid_request validation_failed rate_limited

message

required

string

details

object

key

additional properties

any

Example

{
  "error": {
    "code": "missing_token"
  }
}

Update an employee

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Example

Example

Example

Responses

200

Example

401

Example

403

Example

404

Example

409

Example

Headers

422

Example

Request Body^required