Create an employee

POST

/employees

curl --request POST \
  --url https://api.usepayloom.com/api/v1/employees \
  --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 } ] }'

• Production
• Staging — demo data, `plm_test_` keys

Requires the employees.manage scope.

Authorizations

• ApiKey

Parameters

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

Media typeapplication/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

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

201

Created

Media typeapplication/json

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

object

id

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

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"
}

401

Missing, invalid, revoked or expired key.

Media typeapplication/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.

Media typeapplication/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.

Media typeapplication/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).

Media typeapplication/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"
  }
}