--- title: "Get employees" method: GET path: "/hris/employees" tags: ["Unified HRIS API"] --- # Get employees `GET /hris/employees` Retrieve all employees. Not interested in most fields? You can use our [our Scopes feature](/scopes) 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)` ## 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 — The number of results to return per page. Maximum is 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](https://docs.kombo.dev/ats/getting-started/fetching-data#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. | Path | Added/Removed | Linked Record | | --- | --- | --- | | `employments` | ✓ Yes | ✓ Yes | | `time_off_balances` | ✓ Yes | ✓ Yes | | `manager` | n/a | ✓ Yes | | `group_memberships` | ✓ Yes | ✗ No | | `legal_entity` | n/a | ✓ Yes | | `work_location` | n/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. - `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` 'ACTIVE' | 'PENDING' | 'INACTIVE' | 'LEAVE' — **(⚠️ Deprecated - Use the `employment_statuses` filter instead.)** Filter by the `employment_status` field. - `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. ## Headers - `X-Integration-Id` string, required ## Response `200` GET /hris/employees Positive response - GetHrisEmployeesPositiveResponse - `status` 'success', required - `data` object, required - `next` string, nullable, 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. - `results` object[], required - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing. - `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. - `employee_number` string, nullable, required — The employee’s organization-internal employee number. - `first_name` string, nullable, required — The employee’s first name. - `last_name` string, nullable, required — The employee’s last name. - `nationality` string, nullable, required — The employee’s nationality. - `display_full_name` string, nullable, 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`. - `job_title` string, nullable, required — The employee’s job title. - `work_email` string, nullable — The employee’s work email address. If the email address is invalid, we will set this to `null`. - `personal_email` string, nullable — The employee’s personal email address. If the email address is invalid, we will set this to `null`. - `mobile_phone_number` string, nullable, required — The employee’s mobile phone number. - `ssn` string, nullable, required — The employee’s social security number - `tax_id` string, nullable, required — The employee’s tax ID. - `gender` union — The employee’s gender. - 'MALE' | 'FEMALE' | 'NON_BINARY' | 'NOT_SPECIFIED' - string — If we can't find a clear mapping: The original string passed through. - `ethnicity` union — The employee’s ethnicity. In rare cases where we can’t find a clear mapping, the original string is passed through. - 'WHITE' | 'ASIAN' | 'HISPANIC_LATINO' | 'HAWAIIAN' | 'NATIVE_AMERICAN' | 'BLACK_AFRICAN_AMERICAN' | 'MULTIPLE_ETHNICITIES' | 'DECLINE_TO_SPECIFY' - string — If we can't find a clear mapping: The original string passed through. - `marital_status` union — The employee’s current marital status. In rare cases where we can’t find a clear mapping, the original string is passed through. - 'SINGLE' | 'MARRIED' | 'DOMESTIC_PARTNERSHIP' | 'WIDOWED' | 'DIVORCED' | 'SEPARATED' | 'NOT_MARRIED' - string — If we can't find a clear mapping: The original string passed through. - `employment_status` union — 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. - 'ACTIVE' | 'PENDING' | 'INACTIVE' | 'LEAVE' - string — If we can't find a clear mapping: The original string passed through. - `employment_type` union — 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. - 'FULL_TIME' | 'PART_TIME' | 'CONTRACT' | 'INTERNSHIP' | 'FREELANCE' | 'WORKING_STUDENT' | 'APPRENTICESHIP' | 'TRAINING' - string — If we can't find a clear mapping: The original string passed through. - `weekly_hours` number, double, nullable, required — The employee’s weekly working hours. - `avatar` string, nullable, 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. - `work_location_id` string, nullable, 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. - `legal_entity_id` string, nullable, 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. - `manager_id` string, nullable, required — The Kombo ID of the employee’s manager. The ID can be used to retrieve the manager from the `get employees` endpoint. - `home_address` object, nullable — The employee’s home address. - `city` string, nullable - `country` string, nullable — Contains the ISO2 country code if possible. If not, it contains the original value. - `raw` string, nullable — If we have address data, this is filled with the raw address string. - `state` string, nullable - `street_1` string, nullable — If we can parse the address data, this field contains the first part of the street information. - `street_2` string, nullable - `zip_code` string, nullable - `bank_accounts` object[], nullable — The employee’s bank accounts. - `iban` string, nullable — 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. - `bic` string, nullable — 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. - `account_number` string, nullable — The bank-specific account number. Some companies use the account number field to put the IBAN here. - `holder_name` string, nullable — The name of the holder of this account. - `bank_name` string, nullable — The name of the bank behind this account. - `domestic_bank_routing` object, nullable - `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). - `type` 'GB_SORT_CODE' | 'DE_BANKLEITZAHL' | 'US_ABA_ROUTING_TRANSIT_NUMBER' | 'CA_ROUTING_NUMBER' | 'AU_BSB_CODE' | 'FR_RIB', nullable, 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. - `date_of_birth` string, date-time, nullable, required — The employee’s date of birth. - `start_date` string, date-time, nullable, required — The date the employee started working for the organization. - `termination_date` string, date-time, nullable, required — The date when the employment ends. Can be in the past or future. - `remote_created_at` string, date-time, nullable, required — The date and time the object was created in the remote system. - `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. - `remote_deleted_at` string, date-time, nullable, 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. - `custom_fields` object, nullable, required — A key-value store of fields not covered by the schema. [Read more](/custom-fields) - `integration_fields` object[], required — An array of selected passthrough integration fields. [Read more](/integration-fields) - `id` string, required — The globally unique ID of this object. - `key` string, required — The key of the field in the remote system. - `type` 'DEFAULT' | 'CUSTOM', required — - `DEFAULT`: static fields in the remote system. - `CUSTOM`: fields that are created/editable by the user. - `value` unknown - `label` string, nullable, required — The label of the field. (not always available) - `remote_data` object, nullable, 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. - `employments` object[], required - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing. - `remote_id` string, nullable, 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. - `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. - `job_title` string, nullable, 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. - `pay_rate` number, double, nullable, required — The monetary amount paid to an employee. - `pay_period` union — 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. - 'HOUR' | 'DAY' | 'WEEK' | 'TWO_WEEKS' | 'HALF_MONTH' | 'MONTH' | 'TWO_MONTHS' | 'QUARTER' | 'HALF_YEAR' | 'YEAR' - string — If we can't find a clear mapping: The original string passed through. - `pay_frequency` union — 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. - 'DAILY' | 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY' | 'SEMIMONTHLY' | 'QUARTERLY' | 'SEMIANNUALLY' | 'ANNUALLY' | 'PRO_RATA' - string — If we can't find a clear mapping: The original string passed through. - `employment_type` union — 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. - 'FULL_TIME' | 'PART_TIME' | 'CONTRACT' | 'INTERNSHIP' | 'FREELANCE' | 'WORKING_STUDENT' | 'APPRENTICESHIP' | 'TRAINING' - string — If we can't find a clear mapping: The original string passed through. - `pay_currency` string, nullable, required — The currency that the employee is paid in. Usually returned in [ISO 4217 currency codes](https://www.iso.org/iso-4217-currency-codes.html). - `effective_date` string, date-time, nullable, required — The date of when the employment started. - `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. - `remote_deleted_at` string, date-time, nullable, 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. - `remote_data` object, nullable, 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. - `custom_fields` object, nullable, required — A key-value store of fields not covered by the schema. [Read more](/custom-fields) - `integration_fields` object[], required — An array of selected passthrough integration fields. [Read more](/integration-fields) - `id` string, required — The globally unique ID of this object. - `key` string, required — The key of the field in the remote system. - `type` 'DEFAULT' | 'CUSTOM', required — - `DEFAULT`: static fields in the remote system. - `CUSTOM`: fields that are created/editable by the user. - `value` unknown - `label` string, nullable, required — The label of the field. (not always available) - `time_off_balances` object[], required - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing. - `remote_id` string, nullable, 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. - `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. - `type_id` string, required - `balance` number, double, nullable, required — The amount of time available to the employee. - `balance_unit` 'HOURS' | 'DAYS', nullable, required — The time-unit of the balance. - `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. - `remote_deleted_at` string, date-time, nullable, 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. - `used` number, double, nullable, required — The amount of time used by the employee. - `used_unit` 'HOURS' | 'DAYS', nullable, required — The time-unit of the used time. - `remote_data` object, nullable, 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. - `manager` object, nullable, required - `first_name` string, nullable, required — The employee’s first name. - `last_name` string, nullable, required — The employee’s last name. - `display_full_name` string, nullable, 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`. - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing. - `employee_number` string, nullable, required — The employee’s organization-internal employee number. - `work_email` string, nullable — The employee’s work email address. If the email address is invalid, we will set this to `null`. - `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. - `employment_status` union — 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. - 'ACTIVE' | 'PENDING' | 'INACTIVE' | 'LEAVE' - string — If we can't find a clear mapping: The original string passed through. - `termination_date` string, date-time, nullable, required — The date when the employment ends. Can be in the past or future. - `groups` object[], required - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing. - `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. - `name` string, nullable, required — The name of the group. - `type` 'DEPARTMENT' | 'TEAM' | 'COST_CENTER', nullable, required — Type of the group. - `legal_entity` object, nullable, required - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing. - `remote_id` string, nullable, 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. - `name` string, nullable, required — The legal entity’s name. - `address` object, nullable — The legal entity’s address. - `city` string, nullable - `country` string, nullable — Contains the ISO2 country code if possible. If not, it contains the original value. - `raw` string, nullable — If we have address data, this is filled with the raw address string. - `state` string, nullable - `street_1` string, nullable — If we can parse the address data, this field contains the first part of the street information. - `street_2` string, nullable - `zip_code` string, nullable - `teams` object[], required — **(⚠️ Deprecated - Please use `groups` instead. It includes the same data and the naming is less confusing.)** Maintained field for backwards compatibility. - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing. - `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. - `name` string, nullable, required — The name of the group. - `type` 'DEPARTMENT' | 'TEAM' | 'COST_CENTER', nullable, required — Type of the group. - `work_location` object, nullable, required - `id` string, required — The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing. - `remote_id` string, nullable, 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. - `name` string, nullable, required — The work location’s name - `address` object, nullable — The work location’s address - `city` string, nullable - `country` string, nullable — Contains the ISO2 country code if possible. If not, it contains the original value. - `raw` string, nullable — If we have address data, this is filled with the raw address string. - `state` string, nullable - `street_1` string, nullable — If we can parse the address data, this field contains the first part of the street information. - `street_2` string, nullable - `zip_code` string, nullable - `type` string, nullable, required — The work location’s type. A freeform string. - `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. - `remote_deleted_at` string, date-time, nullable, 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. - `remote_data` object, nullable, 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. ## Other responses - `default` — The standard error response with the error codes for the HRIS use case. --- [API](https://skmtc.net/kombo/apis/kombo-api.md) · [All operations](https://skmtc.net/kombo/apis/kombo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kombo/kombo-api/revisions/fdcb894a4742/schema)