KOkombo
Unified HRIS API

Get employees

Changed on

Retrieve all employees.

<Note>Not interested in most fields? You can use our our Scopes feature to customize what data points are synced.</Note>

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

get/hris/employees

Request

Query parameters

cursorstring

An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.

page_sizeinteger

The number of results to return per page. Maximum is 250.

updated_afterstring date-time

Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, updated_after matches when the returned record changed, or when related data changed as described below.

PathAdded/RemovedLinked Record
employments✓ Yes✓ Yes
time_off_balances✓ Yes✓ Yes
managern/a✓ Yes
group_memberships✓ Yes✗ No
legal_entityn/a✓ Yes
work_locationn/a✓ Yes

Added/Removed: Whether adding or removing entries from this list triggers an update (n/a for single records). Linked Record: Whether changes to the linked record itself trigger an update.

include_deleted'true' | 'false'

By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.

ignore_unsupported_filters'true' | 'false'

When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.

idsstring

Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.

remote_idsstring

Filter by a comma-separated list of remote IDs.

employment_status'ACTIVE' | 'PENDING' | 'INACTIVE' | 'LEAVE'

(⚠️ Deprecated - Use the employment_statuses filter instead.) Filter by the employment_status field.

employment_statusesstring

Filter by a comma-separated list of ACTIVE, PENDING, INACTIVE, LEAVE

  • ACTIVE: the employee is actively employed
  • PENDING: the employee is not actively employed yet (but they signed their contract or are part of an onboarding process)
  • INACTIVE: a full-time employee is no longer employed, or, for a contract worker when their contract runs out
  • LEAVE: the employee is still employed but currently on leave (note that not all HR systems support this status — use our absences API for detailed information)

Leave this blank to get results matching all values.

group_idsstring

Filter by a comma-separated list of group IDs. We will only return employees that are members of any of the groups.

legal_entity_idsstring

Filter by a comma-separated list of legal entity IDs. We will only return employees that are members of any of the legal entities.

work_location_idsstring

Filter by a comma-separated list of work location IDs. We will only return employees who are at any of the work locations.

work_emailsstring

Filter by a comma-separated list of work emails. We will only return employees who have any of the work emails. The format of the emails is case-insensitive.

personal_emailsstring

Filter by a comma-separated list of personal emails. We will only return employees who have any of the personal emails. The format of the emails is case-insensitive.

custom_fieldsstring

A JSON string with a single key-value pair like {"fieldKey":"fieldValue"} to filter employees by a specific custom field value. Note that the value must be a string, number, boolean or null and the key must be a valid custom field key. Custom fields with a value of type array or object are not supported.

Headers

X-Integration-Idstring required

ID of the integration you want to interact with.

Response

GET /hris/employees Positive response

status'success' required

Example response

{
  "data": {
    "next": "eyJwYWdlIjoxMiwibm90ZSI6InRoaXMgaXMganVzdCBhbiBleGFtcGxlIGFuZCBub3QgcmVwcmVzZW50YXRpdmUgZm9yIGEgcmVhbCBjdXJzb3IhIn0=",
    "results": [
      {
        "id": "26vafvWSRmbhNcxJYqjCzuJg",
        "remote_id": "32",
        "employee_number": "3243422",
        "first_name": "John",
        "last_name": "Doe",
        "nationality": "French",
        "display_full_name": "John Doe",
        "job_title": "Integrations Team Lead",
        "work_email": "john.doe@acme.com",
        "personal_email": "john@doe.me",
        "mobile_phone_number": "801-555-4687",
        "ssn": "555-32-6395",
        "tax_id": "12 345 678 901",
        "gender": "MALE",
        "ethnicity": "BLACK_AFRICAN_AMERICAN",
        "marital_status": "MARRIED",
        "employment_status": "INACTIVE",
        "employment_type": "FULL_TIME",
        "weekly_hours": 40,
        "avatar": "https://resources.bamboohr.com/images/photo_person_150x150.png",
        "work_location_id": "7E2gyuv6TmvtByzBxW9Sxt53",
        "legal_entity_id": "xB32bied320csBSsl3XWdlw33",
        "manager_id": "9pf2pxBB8VX8EQMC9aipW2Bo",
        "home_address": {
          "city": "Berlin",
          "country": "DE",
          "raw": "Sonnenallee 63\n12045 Berlin\nGermany",
          "state": "Berlin",
          "street_1": "Sonnenallee 63",
          "street_2": null,
          "zip_code": "12045"
        },
        "bank_accounts": [
          {
            "account_number": "1234567890",
            "bank_name": "Commerzbank",
            "bic": "COBADEFFXXX",
            "domestic_bank_routing": {
              "number": "34567890",
              "type": "DE_BANKLEITZAHL"
            },
            "holder_name": "John Doe",
            "iban": "DE12345678901234567890"
          }
        ],
        "date_of_birth": "1986-01-01T00:00:00.000Z",
        "start_date": "2020-04-07T00:00:00.000Z",
        "termination_date": "2022-05-20T00:00:00.000Z",
        "remote_created_at": "2020-04-07T12:32:01.000Z",
        "changed_at": "2022-08-07T14:01:29.196Z",
        "remote_deleted_at": null,
        "custom_fields": {},
        "integration_fields": [],
        "remote_data": null,
        "employments": [
          {
            "id": "12vpXR7BeqYNWDShXRgsonnm",
            "remote_id": "859",
            "employee_id": "26vafvWSRmbhNcxJYqjCzuJg",
            "job_title": "Social Media Marketer",
            "pay_rate": 85000,
            "pay_period": "YEAR",
            "pay_frequency": "SEMIMONTHLY",
            "employment_type": "FULL_TIME",
            "pay_currency": "EUR",
            "effective_date": "2021-01-30T00:00:00.000Z",
            "changed_at": "2022-08-07T14:01:29.196Z",
            "remote_deleted_at": null,
            "remote_data": null,
            "custom_fields": {},
            "integration_fields": []
          }
        ],
        "time_off_balances": [
          {
            "id": "FuyRuk5NqP3qTcThED3ymTuE",
            "remote_id": "124123",
            "employee_id": "2Up4ZCvq1bFVzmzXG6EWzV3j",
            "type_id": "BQJaBxRCiqN46G27VTegvkEr",
            "balance": 14,
            "balance_unit": "DAYS",
            "changed_at": "2022-08-07T14:01:29.196Z",
            "remote_deleted_at": null,
            "used": 3,
            "used_unit": "DAYS",
            "remote_data": null
          }
        ],
        "manager": {
          "first_name": "John",
          "last_name": "Doe",
          "display_full_name": "John Doe",
          "id": "26vafvWSRmbhNcxJYqjCzuJg",
          "employee_number": "3243422",
          "work_email": "john.doe@acme.com",
          "remote_id": "32",
          "employment_status": "INACTIVE",
          "termination_date": "2022-05-20T00:00:00.000Z"
        },
        "groups": [
          {
            "id": "4B9bKBpX5tnwjiG93TAqF7ci",
            "remote_id": "49",
            "name": "Customer Success",
            "type": "TEAM"
          }
        ],
        "legal_entity": {
          "id": "4B9bKBpX5tnwjiG93TAqF7ci",
          "remote_id": "49",
          "name": "ACME Inc.",
          "address": {
            "city": "Berlin",
            "country": "DE",
            "raw": "Sonnenallee 63\n12045 Berlin, Berlin\nGermany",
            "state": "Berlin",
            "street_1": "Sonnenallee 63",
            "street_2": null,
            "zip_code": "12045"
          }
        },
        "teams": [
          {
            "id": "4B9bKBpX5tnwjiG93TAqF7ci",
            "remote_id": "49",
            "name": "Customer Success",
            "type": "TEAM"
          }
        ],
        "work_location": {
          "id": "22st2Ji8XpncEYEak8mvQgQF",
          "remote_id": "1348",
          "name": "Kombo HQ",
          "address": {
            "city": "Berlin",
            "country": "DE",
            "raw": "Sonnenallee 63\n12045 Berlin, Berlin\nGermany",
            "state": "Berlin",
            "street_1": "Sonnenallee 63",
            "street_2": null,
            "zip_code": "12045"
          },
          "type": "OFFICE",
          "changed_at": "2022-08-07T14:01:29.196Z",
          "remote_deleted_at": "2022-08-07T14:01:29.196Z",
          "remote_data": null,
          "custom_fields": {},
          "integration_fields": []
        }
      }
    ]
  }
}

Changes

  • 485b6d0d03b3Revision changes
    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status

  • 0152248da7d7Revision changes
    • warning

      added the new SG_BANK_BRANCH_CODE enum value to the ////// response property for the response status