List employees

GET

/employees

curl --request GET \
  --url 'https://api.usepayloom.com/api/v1/employees?limit=25&archived=false' \
  --header 'Authorization: Bearer <token>'

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

Requires the employees.read scope.

Authorizations

• ApiKey

Parameters

Query Parameters

limit

integer

default: 25 >= 1 <= 100

starting_after

string format: uuid

The next_cursor from the previous page.

updated_since

string format: date-time

ISO 8601 timestamp; returns only records updated at or after it.

archived

boolean

List archived employees instead of active ones.

Responses

200

OK

Media typeapplication/json

object

object

string

Allowed value: list

data

Array<object>

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

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

has_more

boolean

next_cursor

string format: uuid

nullable

Example

{
  "object": "list",
  "data": [
    {
      "object": "employee",
      "classification": "employee",
      "jurisdiction": "GH",
      "bank_name_check": "matched"
    }
  ]
}

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

429

Too many requests. Honour Retry-After.

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

Seconds to wait.