- Documentation
- HRIS API
- ATS API
- ATS-Assessment API
- Status
- Getting started
Kombo Connect
Filtering
Integrations
Other
Employees
Organization
Time off
DATEV Payroll
General
General API Reference
HRIS API Reference
DATEV API Reference
Get employees
Retrieve all employees.
Create an API key on the Secrets page in the Kombo dashboard.
ID of the integration you want to interact with.
An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
The number of results to return per page.
Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.
By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3. Those IDs are validated to be 24 characters long and to exist for this integration in the database. If any of the IDs are don't exist, the endpoint will return a 404 error.
Filter by a comma-separated list of remote IDs.
(⚠️ Deprecated - Use the employment_statuses filter instead.) Filter by the employment_status field.
Filter by a comma-separated list of ACTIVE, PENDING, INACTIVE, LEAVE
ACTIVE: the employee is actively employedPENDING: 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 outLEAVE: 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.
Filter by a comma-separated list of group IDs. We will only return employees that are members of any of the groups.
Filter by a comma-separated list of legal entity IDs. We will only return employees that are members of any of the legal entities.
Filter by a comma-separated list of work location IDs. We will only return employees who are at any of the work locations.
Filter by a comma-separated list of work emails. We will only return employees who have any of the work emails.
Filter by a comma-separated list of personal emails. We will only return employees who have any of the personal emails.
curl --request GET \
--url https://api.kombo.dev/v1/hris/employees \
--header 'Authorization: Bearer <token>' \
--header 'X-Integration-Id: <x-integration-id>'{
"status": "success",
"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": {},
"remote_data": null,
"employments": [
{
"id": "12vpXR7BeqYNWDShXRgsonnm",
"remote_id": "859",
"employee_id": "8Xk99QfVKYA6vfEafEUBdEPJ",
"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": {}
}
],
"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",
"work_email": "john.doe@acme.com",
"remote_id": "32"
},
"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
}
}
]
}
}This feature is currently available for the following integrations:
Personio
Workday
Workday Custom Reports
Workday Custom Report SFTP
SAP SuccessFactors
Factorial
UKG Pro
rexx systems
AFAS Software
BambooHR
PayFit Customer
PayFit Partner
PayFit
Kenjo
HeavenHR
HiBob
Cezanne HR
Entra ID
Azure AD
Google Workspace
Deel
Remote
Okta
Sage HR
Humaans
Eurécia
Oracle HCM
Officient
Sesame HR
Charlie
HRworks
Abacus
Zoho People
Gusto
Breathe HR
CatalystOne
Mirus
AlexisHR
Rippling
Sapling
Nmbrs
PeopleHR
Lucca
Zelt
Planday
Hailey HR
Sympa
IRIS Cascade
Kombo Sandbox
SFTP
You’d like to see this feature for another integration? Please reach out! We’re always happy to discuss extending our coverage.
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
Create an API key on the Secrets page in the Kombo dashboard.
Headers
ID of the integration you want to interact with.
Query Parameters
An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
The number of results to return per page.
Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.
By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
true, false Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3. Those IDs are validated to be 24 characters long and to exist for this integration in the database. If any of the IDs are don't exist, the endpoint will return a 404 error.
Filter by a comma-separated list of remote IDs.
(⚠️ Deprecated - Use the employment_statuses filter instead.) Filter by the employment_status field.
ACTIVE, PENDING, INACTIVE, LEAVE Filter by a comma-separated list of ACTIVE, PENDING, INACTIVE, LEAVE
ACTIVE: the employee is actively employedPENDING: 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 outLEAVE: 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.
Filter by a comma-separated list of group IDs. We will only return employees that are members of any of the groups.
Filter by a comma-separated list of legal entity IDs. We will only return employees that are members of any of the legal entities.
Filter by a comma-separated list of work location IDs. We will only return employees who are at any of the work locations.
Filter by a comma-separated list of work emails. We will only return employees who have any of the work emails.
Filter by a comma-separated list of personal emails. We will only return employees who have any of the personal emails.
Response
success 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.
The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
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.
An optional, organization-internal employee number.
The employee’s first name.
The employee’s last name.
The employee’s nationality.
The employee’s full name, including middle names. Not all HR systems provide an explicit display name, so we recommend falling back to first_name and last_name.
The employee’s job title.
The employee’s work email address. If the email address is invalid, we will set this to null.
The employee’s personal email address. If the email address is invalid, we will set this to null.
Social security number
One of 4 standardized values (MALE, FEMALE, NON_BINARY, or NOT_SPECIFIED) or — in rare cases where can't find a clear mapping — the original string passed through.
MALE, FEMALE, NON_BINARY, NOT_SPECIFIED One of 8 standardized values (WHITE, ASIAN, HISPANIC_LATINO, HAWAIIAN, NATIVE_AMERICAN, BLACK_AFRICAN_AMERICAN, MULTIPLE_ETHNICITIES, or DECLINE_TO_SPECIFY) or — in rare cases where can't find a clear mapping — the original string passed through.
WHITE, ASIAN, HISPANIC_LATINO, HAWAIIAN, NATIVE_AMERICAN, BLACK_AFRICAN_AMERICAN, MULTIPLE_ETHNICITIES, DECLINE_TO_SPECIFY One of 7 standardized values (SINGLE, MARRIED, DOMESTIC_PARTNERSHIP, WIDOWED, DIVORCED, SEPARATED, or NOT_MARRIED) or — in rare cases where can't find a clear mapping — the original string passed through.
SINGLE, MARRIED, DOMESTIC_PARTNERSHIP, WIDOWED, DIVORCED, SEPARATED, NOT_MARRIED The current employment status of the employee:
ACTIVE: the employee is actively employedPENDING: 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 anymoreLEAVE: 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)
Please note that in rare cases, where we can't find a clear mapping, the original string is passed through.
ACTIVE, PENDING, INACTIVE, LEAVE One of 8 standardized values (FULL_TIME, PART_TIME, CONTRACT, INTERNSHIP, FREELANCE, WORKING_STUDENT, APPRENTICESHIP, or TRAINING) or — in rare cases where can't find a clear mapping — the original string passed through.
FULL_TIME, PART_TIME, CONTRACT, INTERNSHIP, FREELANCE, WORKING_STUDENT, APPRENTICESHIP, TRAINING The employee's weekly working hours.
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.
The ID of the employee’s work location. Can be used to retrieve the work location from the hris_locations endpoint.
The ID of the employee’s legal entity.
Contains the ISO2 country code if possible. If not, it contains the original value.
If we have address data, this is filled with the raw address string.
If we can parse the address data, this field contains the first part of the street information.
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.
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.
The bank-specific account number. Some companies use the account number field to put the IBAN here.
The name of the holder of this account.
The name of the bank behind this account.
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).
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.
GB_SORT_CODE, DE_BANKLEITZAHL, US_ABA_ROUTING_TRANSIT_NUMBER, CA_ROUTING_NUMBER, AU_BSB_CODE YYYY-MM-DDTHH:mm:ss.sssZ
The date the employee started working for the organization.
The date when the employment ends. Can be in the past or future.
The date and time the object was created in the remote system.
The timestamp when this object was last changed. This value is tracked by Kombo based on changes in the data.
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.
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.
(⚠️ Deprecated) We now provide the job_title directly on the employee model.
One of 10 standardized values (HOUR, DAY, WEEK, TWO_WEEKS, HALF_MONTH, MONTH, TWO_MONTHS, QUARTER, HALF_YEAR, or YEAR) or — in rare cases where can't find a clear mapping — the original string passed through.
HOUR, DAY, WEEK, TWO_WEEKS, HALF_MONTH, MONTH, TWO_MONTHS, QUARTER, HALF_YEAR, YEAR One of 9 standardized values (DAILY, WEEKLY, BIWEEKLY, MONTHLY, SEMIMONTHLY, QUARTERLY, SEMIANNUALLY, ANNUALLY, or PRO_RATA) or — in rare cases where can't find a clear mapping — the original string passed through.
DAILY, WEEKLY, BIWEEKLY, MONTHLY, SEMIMONTHLY, QUARTERLY, SEMIANNUALLY, ANNUALLY, PRO_RATA One of 8 standardized values (FULL_TIME, PART_TIME, CONTRACT, INTERNSHIP, FREELANCE, WORKING_STUDENT, APPRENTICESHIP, or TRAINING) or — in rare cases where can't find a clear mapping — the original string passed through.
FULL_TIME, PART_TIME, CONTRACT, INTERNSHIP, FREELANCE, WORKING_STUDENT, APPRENTICESHIP, TRAINING Pay currency usually returned in ISO 4217 currency codes.
YYYY-MM-DDTHH:mm:ss.sssZ
YYYY-MM-DDTHH:mm:ss.sssZ
YYYY-MM-DDTHH:mm:ss.sssZ
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.
The amount time available to the employee.
HOURS, DAYS YYYY-MM-DDTHH:mm:ss.sssZ
YYYY-MM-DDTHH:mm:ss.sssZ
HOURS, DAYS 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.
The employee’s first name.
The employee’s last name.
The employee’s full name, including middle names. Not all HR systems provide an explicit display name, so we recommend falling back to first_name and last_name.
The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
The employee’s work email address. If the email address is invalid, we will set this to null.
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.
Type of the group. Can be any of DEPARTMENT, TEAM, and COST_CENTER
DEPARTMENT, TEAM, COST_CENTER The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
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.
Contains the ISO2 country code if possible. If not, it contains the original value.
If we have address data, this is filled with the raw address string.
If we can parse the address data, this field contains the first part of the street information.
(⚠️ Deprecated - Please use groups instead. It includes the same data and the naming is less confusing.) Maintained field for backwards compatibility.
Type of the group. Can be any of DEPARTMENT, TEAM, and COST_CENTER
DEPARTMENT, TEAM, COST_CENTER Contains the ISO2 country code if possible. If not, it contains the original value.
If we have address data, this is filled with the raw address string.
If we can parse the address data, this field contains the first part of the street information.
YYYY-MM-DDTHH:mm:ss.sssZ
YYYY-MM-DDTHH:mm:ss.sssZ
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.
curl --request GET \
--url https://api.kombo.dev/v1/hris/employees \
--header 'Authorization: Bearer <token>' \
--header 'X-Integration-Id: <x-integration-id>'{
"status": "success",
"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": {},
"remote_data": null,
"employments": [
{
"id": "12vpXR7BeqYNWDShXRgsonnm",
"remote_id": "859",
"employee_id": "8Xk99QfVKYA6vfEafEUBdEPJ",
"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": {}
}
],
"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",
"work_email": "john.doe@acme.com",
"remote_id": "32"
},
"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
}
}
]
}
}