List employees

GET

/employees

const url = 'https://api.usepayloom.com/api/v1/employees?limit=25&archived=false';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

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

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

application/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

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

has_more

boolean

next_cursor

string format: uuid

nullable

Example

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

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

429

Too many requests. Honour Retry-After.

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

Seconds to wait.