Get employees

Supported integrations

This feature is currently available for the following integrations:

You’d like to see this feature for another integration? Please reach out! We’re always happy to discuss extending our coverage.

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

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)

Authorizations

Authorization

string

header

required

Create an API key on the Secrets page in the Kombo dashboard.

Headers

X-Integration-Id

string

required

ID of the integration you want to interact with.

Query Parameters

cursor

string

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

page_size

integer<int64>

default:100

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

Required range: 1 <= x <= 250

updated_after

string<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.

include_deleted

enum<string>

default:false

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

Available options:

true,

false

ids

string

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

remote_ids

string

Filter by a comma-separated list of remote IDs.

employment_status

enum<string>

deprecated

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

Available options:

ACTIVE,

PENDING,

INACTIVE,

LEAVE

employment_statuses

string

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_ids

string

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

legal_entity_ids

string

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_ids

string

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

work_emails

string

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_emails

string

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_fields

string

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.

Response

GET /hris/employees Positive response

status

string

required

Allowed value: "success"

data

object

required

Show child attributes

data.next

string | null

required

Cursor string that can be passed to the cursor query parameter to get the next page. If this is null, then there are no more pages.

data.results

object[]

required

Show child attributes

data.results.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.results.remote_id

string

required

The raw ID of the object in the remote system. We don't recommend using this as a primary key on your side as it might sometimes be compromised of multiple identifiers if a system doesn't provide a clear primary key.

data.results.employee_number

string | null

required

The employee’s organization-internal employee number.

data.results.first_name

string | null

required

The employee’s first name.

data.results.last_name

string | null

required

The employee’s last name.

data.results.nationality

string | null

required

The employee’s nationality.

data.results.display_full_name

string | null

required

The employee’s full name, including any middle names. Not all HR systems provide an explicit display name, so we recommend falling back to first_name and last_name.

data.results.job_title

string | null

required

The employee’s job title.

data.results.mobile_phone_number

string | null

required

The employee’s mobile phone number.

data.results.ssn

string | null

required

The employee’s social security number

data.results.tax_id

string | null

required

The employee’s tax ID.

data.results.weekly_hours

number<double> | null

required

The employee’s weekly working hours.

Required range: x >= -1.7976931348623157e+308

data.results.avatar

string | null

required

URL to the employee’s avatar. This is either the raw URL from the HR system (in cases where it can be requested without short-lived authentication) or a URL to a temporarily cached version of the file hosted by Kombo. Kombo will delete the cached file after its deletion in the source system.

data.results.work_location_id

string | null

required

The Kombo ID of the employee’s work location. The ID can be used to retrieve the work location from the get work locations endpoint.

data.results.legal_entity_id

string | null

required

The Kombo ID of the employee’s legal entity. The ID can be used to retrieve the legal entity from the get legal entities endpoint.

data.results.manager_id

string | null

required

The Kombo ID of the employee’s manager. The ID can be used to retrieve the manager from the get employees endpoint.

data.results.date_of_birth

string<date-time> | null

required

The employee’s date of birth.

data.results.start_date

string<date-time> | null

required

The date the employee started working for the organization.

data.results.termination_date

string<date-time> | null

required

The date when the employment ends. Can be in the past or future.

data.results.remote_created_at

string<date-time> | null

required

The date and time the object was created in the remote system.

data.results.changed_at

string<date-time>

required

The timestamp when this specific record was last modified. This field only updates when properties directly on this record change, NOT when related or nested models change. For filtering that considers nested data changes, use the updated_after parameter which will return records when either the record itself OR its related models have been updated.

data.results.remote_deleted_at

string<date-time> | null

required

The date and time the object was deleted in the remote system. Objects are automatically marked as deleted when Kombo can't retrieve them from the remote system anymore. Kombo will also anonymize entries 14 days after they disappear.

data.results.custom_fields

object

required

A key-value store of fields not covered by the schema. Read more

data.results.integration_fields

object[]

required

An array of selected passthrough integration fields. Read more

Show child attributes

data.results.integration_fields.id

string

required

The globally unique ID of this object.

data.results.integration_fields.key

string

required

The key of the field in the remote system.

data.results.integration_fields.type

enum<string>

required

DEFAULT: static fields in the remote system.
CUSTOM: fields that are created/editable by the user.

Available options:

DEFAULT,

CUSTOM

data.results.integration_fields.label

string | null

required

The label of the field. (not always available)

data.results.integration_fields.value

null

The field's value.

data.results.remote_data

object

required

Includes the data fetched from the remote system. Please be aware that including this in you scope config might violate other scopes that are set.

Remote data always has the endpoint path that we got the data from as the top level key. For example, it could look like: { "/companies": { ... }}

This is not available on all plans. Reach out to Kombo if you need it.

data.results.employments

object[]

required

Show child attributes

data.results.employments.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.results.employments.remote_id

string | null

required

data.results.employments.employee_id

string

required

The Kombo ID of the employment’s employee. The ID can be used to retrieve the employee from the get employees endpoint.

data.results.employments.job_title

string | null

required

This field can contain historic job titles. Please use the job_title field on the employee for the active job title of an employee.

data.results.employments.pay_rate

number<double> | null

required

The monetary amount paid to an employee.

Required range: x >= -1.7976931348623157e+308

data.results.employments.pay_currency

string | null

required

The currency that the employee is paid in. Usually returned in ISO 4217 currency codes.

data.results.employments.effective_date

string<date-time> | null

required

The date of when the employment started.

data.results.employments.changed_at

string<date-time>

required

data.results.employments.remote_deleted_at

string<date-time> | null

required

data.results.employments.remote_data

object

required

Includes the data fetched from the remote system. Please be aware that including this in you scope config might violate other scopes that are set.

Remote data always has the endpoint path that we got the data from as the top level key. For example, it could look like: { "/companies": { ... }}

This is not available on all plans. Reach out to Kombo if you need it.

data.results.employments.custom_fields

object

required

A key-value store of fields not covered by the schema. Read more

data.results.employments.integration_fields

object[]

required

An array of selected passthrough integration fields. Read more

Show child attributes

data.results.employments.integration_fields.id

string

required

The globally unique ID of this object.

data.results.employments.integration_fields.key

string

required

The key of the field in the remote system.

data.results.employments.integration_fields.type

enum<string>

required

DEFAULT: static fields in the remote system.
CUSTOM: fields that are created/editable by the user.

Available options:

DEFAULT,

CUSTOM

data.results.employments.integration_fields.label

string | null

required

The label of the field. (not always available)

data.results.employments.integration_fields.value

null

The field's value.

data.results.employments.pay_period

The time interval which the pay_rate is describing.

A pay_rate value of 12000 with a pay_period of YEAR would indicate that the employee receives 12000 over the course of a year. In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

HOUR,

DAY,

WEEK,

TWO_WEEKS,

HALF_MONTH,

MONTH,

TWO_MONTHS,

QUARTER,

HALF_YEAR,

YEAR

data.results.employments.pay_frequency

The time interval at which the employee receives payment.

A pay_rate of 12000, with a pay_period of YEAR, and a pay_frequency of MONTHLY would indicate that the employee is paid 1000 every month. In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

DAILY,

WEEKLY,

BIWEEKLY,

MONTHLY,

SEMIMONTHLY,

QUARTERLY,

SEMIANNUALLY,

ANNUALLY,

PRO_RATA

data.results.employments.employment_type

The employee’s current employment type:

FULL_TIME: the employee is actively employed
PART_TIME: the employee is working only part of the usual working hours
CONTRACT: the employee is working temporarily under a contract
INTERNSHIP: the employee is working as an intern
FREELANCE: the employee is working as a freelancer
WORKING_STUDENT: the employee is working as a working student
APPRENTICESHIP: the employee is working in an apprenticeship
TRAINING: the employee is working in a training program

In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

FULL_TIME,

PART_TIME,

CONTRACT,

INTERNSHIP,

FREELANCE,

WORKING_STUDENT,

APPRENTICESHIP,

TRAINING

data.results.time_off_balances

object[]

required

Show child attributes

data.results.time_off_balances.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.results.time_off_balances.remote_id

string | null

required

data.results.time_off_balances.employee_id

string

required

The Kombo ID of the employee to which the balance belongs to. The ID can be used to retrieve the employee from the get employees endpoint.

data.results.time_off_balances.type_id

string

required

data.results.time_off_balances.balance

number<double> | null

required

The amount of time available to the employee.

Required range: x >= -1.7976931348623157e+308

data.results.time_off_balances.balance_unit

enum<string> | null

required

The time-unit of the balance.

Available options:

HOURS,

DAYS

data.results.time_off_balances.changed_at

string<date-time>

required

data.results.time_off_balances.remote_deleted_at

string<date-time> | null

required

data.results.time_off_balances.used

number<double> | null

required

The amount of time used by the employee.

Required range: x >= -1.7976931348623157e+308

data.results.time_off_balances.used_unit

enum<string> | null

required

The time-unit of the used time.

Available options:

HOURS,

DAYS

data.results.time_off_balances.remote_data

object

required

Includes the data fetched from the remote system. Please be aware that including this in you scope config might violate other scopes that are set.

Remote data always has the endpoint path that we got the data from as the top level key. For example, it could look like: { "/companies": { ... }}

This is not available on all plans. Reach out to Kombo if you need it.

data.results.manager

object

required

Show child attributes

data.results.manager.first_name

string | null

required

The employee’s first name.

data.results.manager.last_name

string | null

required

The employee’s last name.

data.results.manager.display_full_name

string | null

required

The employee’s full name, including any middle names. Not all HR systems provide an explicit display name, so we recommend falling back to first_name and last_name.

data.results.manager.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.results.manager.employee_number

string | null

required

The employee’s organization-internal employee number.

data.results.manager.remote_id

string

required

data.results.manager.termination_date

string<date-time> | null

required

The date when the employment ends. Can be in the past or future.

data.results.manager.work_email

string | null

The employee’s work email address. If the email address is invalid, we will set this to null.

data.results.manager.employment_status

The employee’s current employment status:

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: the employee is not actively employed anymore
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)

In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

ACTIVE,

PENDING,

INACTIVE,

LEAVE

data.results.groups

object[]

required

Show child attributes

data.results.groups.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.results.groups.remote_id

string

required

data.results.groups.name

string | null

required

The name of the group.

data.results.groups.type

enum<string> | null

required

Type of the group.

Available options:

DEPARTMENT,

TEAM,

COST_CENTER

data.results.legal_entity

object

required

Show child attributes

data.results.legal_entity.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.results.legal_entity.remote_id

string | null

required

data.results.legal_entity.name

string | null

required

The legal entity’s name.

data.results.legal_entity.address

object

The legal entity’s address.

Show child attributes

data.results.legal_entity.address.city

string | null

data.results.legal_entity.address.country

string | null

Contains the ISO2 country code if possible. If not, it contains the original value.

data.results.legal_entity.address.raw

string | null

If we have address data, this is filled with the raw address string.

data.results.legal_entity.address.state

string | null

data.results.legal_entity.address.street_1

string | null

If we can parse the address data, this field contains the first part of the street information.

data.results.legal_entity.address.street_2

string | null

data.results.legal_entity.address.zip_code

string | null

data.results.teams

object[]

required

deprecated

(⚠️ Deprecated - Please use groups instead. It includes the same data and the naming is less confusing.) Maintained field for backwards compatibility.

Show child attributes

data.results.teams.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.results.teams.remote_id

string

required

data.results.teams.name

string | null

required

The name of the group.

data.results.teams.type

enum<string> | null

required

Type of the group.

Available options:

DEPARTMENT,

TEAM,

COST_CENTER

data.results.work_location

object

required

Show child attributes

data.results.work_location.id

string

required

The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.

data.results.work_location.remote_id

string | null

required

data.results.work_location.name

string | null

required

The work location’s name

data.results.work_location.type

string | null

required

The work location’s type. A freeform string.

data.results.work_location.changed_at

string<date-time>

required

data.results.work_location.remote_deleted_at

string<date-time> | null

required

data.results.work_location.remote_data

object

required

Includes the data fetched from the remote system. Please be aware that including this in you scope config might violate other scopes that are set.

Remote data always has the endpoint path that we got the data from as the top level key. For example, it could look like: { "/companies": { ... }}

This is not available on all plans. Reach out to Kombo if you need it.

data.results.work_location.address

object

The work location’s address

Show child attributes

data.results.work_location.address.city

string | null

data.results.work_location.address.country

string | null

Contains the ISO2 country code if possible. If not, it contains the original value.

data.results.work_location.address.raw

string | null

If we have address data, this is filled with the raw address string.

data.results.work_location.address.state

string | null

data.results.work_location.address.street_1

string | null

If we can parse the address data, this field contains the first part of the street information.

data.results.work_location.address.street_2

string | null

data.results.work_location.address.zip_code

string | null

data.results.work_email

string | null

The employee’s work email address. If the email address is invalid, we will set this to null.

data.results.personal_email

string | null

The employee’s personal email address. If the email address is invalid, we will set this to null.

data.results.gender

The employee’s gender.

Available options:

MALE,

FEMALE,

NON_BINARY,

NOT_SPECIFIED

data.results.ethnicity

The employee’s ethnicity. In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

WHITE,

ASIAN,

HISPANIC_LATINO,

HAWAIIAN,

NATIVE_AMERICAN,

BLACK_AFRICAN_AMERICAN,

MULTIPLE_ETHNICITIES,

DECLINE_TO_SPECIFY

data.results.marital_status

The employee’s current marital status. In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

SINGLE,

MARRIED,

DOMESTIC_PARTNERSHIP,

WIDOWED,

DIVORCED,

SEPARATED,

NOT_MARRIED

data.results.employment_status

The employee’s current employment status:

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: the employee is not actively employed anymore
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)

In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

ACTIVE,

PENDING,

INACTIVE,

LEAVE

data.results.employment_type

The employee’s current employment type:

FULL_TIME: the employee is actively employed
PART_TIME: the employee is working only part of the usual working hours
CONTRACT: the employee is working temporarily under a contract
INTERNSHIP: the employee is working as an intern
FREELANCE: the employee is working as a freelancer
WORKING_STUDENT: the employee is working as a working student
APPRENTICESHIP: the employee is working in an apprenticeship
TRAINING: the employee is working in a training program

In rare cases where we can’t find a clear mapping, the original string is passed through.

Available options:

FULL_TIME,

PART_TIME,

CONTRACT,

INTERNSHIP,

FREELANCE,

WORKING_STUDENT,

APPRENTICESHIP,

TRAINING

data.results.home_address

object

The employee’s home address.

Show child attributes

data.results.home_address.city

string | null

data.results.home_address.country

string | null

Contains the ISO2 country code if possible. If not, it contains the original value.

data.results.home_address.raw

string | null

If we have address data, this is filled with the raw address string.

data.results.home_address.state

string | null

data.results.home_address.street_1

string | null

If we can parse the address data, this field contains the first part of the street information.

data.results.home_address.street_2

string | null

data.results.home_address.zip_code

string | null

data.results.bank_accounts

object[] | null

The employee’s bank accounts.

Show child attributes

data.results.bank_accounts.iban

string | null

The internationally unique IBAN identifying this account. If we detect a valid IBAN from the account number and this field would otherwise be empty, we will automatically populate this field.

data.results.bank_accounts.bic

string | null

The internationally unique BIC/SWIFT code identifying the bank behind this account. If we detect a valid BIC from the domestic bank routing number and this field would otherwise be empty, we will automatically populate this field.

data.results.bank_accounts.account_number

string | null

The bank-specific account number. Some companies use the account number field to put the IBAN here.

data.results.bank_accounts.holder_name

string | null

The name of the holder of this account.

data.results.bank_accounts.bank_name

string | null

The name of the bank behind this account.

data.results.bank_accounts.domestic_bank_routing

object

Show child attributes

data.results.bank_accounts.domestic_bank_routing.number

string

required

Bank routing number (e.g. DE Bankleitzahl, GB Sort Code, US ABA routing number, AU BSB code). This field is not formatted and therefore might contain delimiters (eg. 01-23-45).

data.results.bank_accounts.domestic_bank_routing.type

enum<string> | null

required

Enum of the routing type, prefixed with the iso-3166-1-alpha-2 banks origin country. If there is uncertainty about the type, it will be set to null.

Available options:

GB_SORT_CODE,

DE_BANKLEITZAHL,

US_ABA_ROUTING_TRANSIT_NUMBER,

CA_ROUTING_NUMBER,

AU_BSB_CODE,

FR_RIB

General

Features

Guides

HRIS API Reference

General API Reference

DATEV

Get employees

Authorizations

Headers

Query Parameters

Response