Kombo Unified HRIS API API
Unified endpoints to access all the HR concepts you might need.
OpenAPI Specification
openapi: 3.1.0
info:
title: Kombo AI Apply Unified HRIS API API
version: 1.0.0
description: Endpoints for AI-powered job application features.
servers:
- url: https://api.kombo.dev/v1
description: Kombo EU API
- url: https://api.us.kombo.dev/v1
description: Kombo US API
security:
- ApiKey: []
tags:
- name: Unified HRIS API
description: Unified endpoints to access all the HR concepts you might need.
paths:
/hris/provisioning-groups/{group_id}/diff:
post:
operationId: PostHrisProvisioningGroupsGroupIdDiff
summary: Get provisioning diff
description: Get the list of users to provision, deprovision, and optionally update based on the users you've already provisioned in your system.
tags:
- Unified HRIS API
parameters:
- in: header
name: X-Integration-Id
schema:
type: string
description: ID of the integration you want to interact with.
example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
required: true
- name: group_id
in: path
required: true
description: ID of the provisioning group (currently only `default` is allowed).
schema:
$ref: '#/components/schemas/PostHrisProvisioningGroupsGroupIdDiffParameterGroupId'
examples:
example1:
value: n39n320clr8c5amf8v83nbch
requestBody:
description: POST /hris/provisioning-groups/:group_id/diff Request body
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisProvisioningGroupsGroupIdDiffRequestBody'
examples:
example1:
value:
provisioned_users:
- origin_id: your_id_123
email: johndoe@example.com
options:
employee_fields:
- id
- first_name
- last_name
responses:
'200':
description: POST /hris/provisioning-groups/:group_id/diff Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisProvisioningGroupsGroupIdDiffPositiveResponse'
default:
$ref: '#/components/responses/ErrorResponseHRIS'
/hris/provisioning-groups/{group_id}/setup-links:
post:
operationId: PostHrisProvisioningGroupsGroupIdSetupLinks
summary: Create provisioning setup link (deprecated)
description: "Create a new link that can be passed to the Kombo Connect SDK to open the provisioning setup UI.\n\n<Warning>\n **This endpoint is deprecated!**\n\n Please use the [Create Setup Flow link endpoint](/v1/post-integrations-integration-id-setup-link) instead. It supports the full Setup Flow (including filtering, field mapping, and any other enabled steps) and works for any integration category, not just HRIS.\n</Warning>"
tags:
- Unified HRIS API
parameters:
- in: header
name: X-Integration-Id
schema:
type: string
description: ID of the integration you want to interact with.
example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
required: true
- name: group_id
in: path
required: true
description: ID of the provisioning group (currently only `default` is allowed).
schema:
$ref: '#/components/schemas/PostHrisProvisioningGroupsGroupIdSetupLinksParameterGroupId'
examples:
example1:
value: n39n320clr8c5amf8v83nbch
requestBody:
description: POST /hris/provisioning-groups/:group_id/setup-links Request body
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisProvisioningGroupsGroupIdSetupLinksRequestBody'
examples:
example1:
value:
language: en
responses:
'200':
description: POST /hris/provisioning-groups/:group_id/setup-links Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisProvisioningGroupsGroupIdSetupLinksPositiveResponse'
examples:
example1:
value:
status: success
data:
url: https://connect.kombo.dev/v1/setup?token=GinuMJCpUQ9xdpLmD2ocw8qdiK3qiPCizDCv754EXri2vAX4
expires_at: '2023-10-11T12:00:00.000Z'
default:
$ref: '#/components/responses/ErrorResponseHRIS'
/hris/employees:
get:
operationId: GetHrisEmployees
summary: Get employees
description: 'Retrieve all employees.
<Note>Not interested in most fields? You can use our [our Scopes feature](/scopes) 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)`'
tags:
- Unified HRIS API
parameters:
- in: header
name: X-Integration-Id
schema:
type: string
description: ID of the integration you want to interact with.
example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
required: true
- name: cursor
in: query
required: false
description: An optional cursor string used for pagination. This can be retrieved from the `next` property of the previous page response.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterCursor'
- name: page_size
in: query
required: false
description: The number of results to return per page. Maximum is 250.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterPageSize'
- name: updated_after
in: query
required: false
description: '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._'
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterUpdatedAfter'
- name: include_deleted
in: query
required: false
description: By default, deleted entries are not returned. Use the `include_deleted` query param to include deleted entries too.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterIncludeDeleted'
- name: ignore_unsupported_filters
in: query
required: false
description: When set to `true`, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterIgnoreUnsupportedFilters'
- name: ids
in: query
required: false
description: Filter by a comma-separated list of IDs such as `222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3`.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterIds'
- name: remote_ids
in: query
required: false
description: Filter by a comma-separated list of remote IDs.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterRemoteIds'
- name: employment_status
in: query
required: false
description: '**(⚠️ Deprecated - Use the `employment_statuses` filter instead.)** Filter by the `employment_status` field.'
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterEmploymentStatus'
- name: employment_statuses
in: query
required: false
description: "Filter by a comma-separated list of `ACTIVE`, `PENDING`, `INACTIVE`, `LEAVE` \n* `ACTIVE`: the employee is **actively employed** \n* `PENDING`: the employee is **not actively employed yet** (but they signed their contract or are part of an onboarding process) \n* `INACTIVE`: a full-time employee is no longer employed, or, for a contract worker when their contract runs out \n* `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) \n \n\nLeave this blank to get results matching all values."
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterEmploymentStatuses'
- name: group_ids
in: query
required: false
description: Filter by a comma-separated list of group IDs. We will only return employees that are members of _any_ of the groups.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterGroupIds'
- name: legal_entity_ids
in: query
required: false
description: Filter by a comma-separated list of legal entity IDs. We will only return employees that are members of _any_ of the legal entities.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterLegalEntityIds'
- name: work_location_ids
in: query
required: false
description: Filter by a comma-separated list of work location IDs. We will only return employees who are at _any_ of the work locations.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterWorkLocationIds'
- name: work_emails
in: query
required: false
description: 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.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterWorkEmails'
- name: personal_emails
in: query
required: false
description: 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.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterPersonalEmails'
- name: custom_fields
in: query
required: false
description: 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.
schema:
$ref: '#/components/schemas/GetHrisEmployeesParameterCustomFields'
responses:
'200':
description: GET /hris/employees Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/GetHrisEmployeesPositiveResponse'
examples:
example1:
value:
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
12045 Berlin
Germany'
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
12045 Berlin, Berlin
Germany'
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
12045 Berlin, Berlin
Germany'
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
default:
$ref: '#/components/responses/ErrorResponseHRIS'
post:
operationId: PostHrisEmployees
summary: '[DEPRECATED] Create employee'
description: "Create a new employee.\n\n<Warning>\n We are deprecating this endpoint in favor of the new [create employee form](/hris/features/create-employee) endpoint.\n</Warning>\n\n<Note>\n This endpoint requires the permission **Create and manage employees** to be enabled in [your scope config](/scopes).\n</Note>\n\n### Example Request Body\n\n```json\n{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"work_email\": \"john.doe@acme.com\",\n \"gender\": \"MALE\",\n \"date_of_birth\": \"1986-01-01\",\n \"start_date\": \"2020-04-07\",\n \"job_title\": \"Integrations Team Lead\",\n \"home_address\": {\n \"city\": \"Berlin\",\n \"country\": \"DE\",\n \"state\": \"Berlin\",\n \"street_1\": \"Sonnenallee 63\",\n \"zip_code\": \"12045\"\n }\n}\n```"
tags:
- Unified HRIS API
parameters:
- in: header
name: X-Integration-Id
schema:
type: string
description: ID of the integration you want to interact with.
example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
required: true
requestBody:
description: POST /hris/employees Request body
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisEmployeesRequestBody'
examples:
example1:
value:
first_name: John
last_name: Doe
work_email: john.doe@acme.com
gender: MALE
date_of_birth: '1986-01-01'
start_date: '2020-04-07'
job_title: Integrations Team Lead
home_address:
city: Berlin
country: DE
state: Berlin
street_1: Sonnenallee 63
zip_code: '12045'
responses:
'200':
description: POST /hris/employees Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisEmployeesPositiveResponse'
examples:
example1:
value:
status: success
data:
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
12045 Berlin
Germany'
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
warnings:
- message: This is an example warning!
default:
$ref: '#/components/responses/ErrorResponseHRIS'
/hris/employees/form:
get:
operationId: GetHrisEmployeesForm
summary: Get employee form
description: "Get the form for creating an employee. This form can be rendered dynamically on your frontend to allow your customers to create employees in their HRIS.\n\nFollow our [create employee guide here](/hris/features/create-employee) to learn how this form is generated and how you can use it.\n\n### Example Form\n```json\n{\n \"properties\": {\n \"firstName\": {\n \"type\": \"text\",\n \"label\": \"First Name\",\n \"required\": true,\n \"description\": \"Employee's first name\",\n \"unified_key\": \"first_name\",\n \"min_length\": 1,\n \"max_length\": 100\n },\n \"startDate\": {\n \"type\": \"date\",\n \"label\": \"Start Date\",\n \"required\": true,\n \"description\": \"Employee's start date\",\n \"unified_key\": \"start_date\"\n },\n \"workLocation\": {\n \"type\": \"object\",\n \"label\": \"Work Location\",\n \"required\": false,\n \"description\": \"Employee's work location\",\n \"unified_key\": null,\n \"properties\": {\n \"site\": {\n \"type\": \"single_select\",\n \"label\": \"Site\",\n \"required\": true,\n \"description\": \"Employee's site\",\n \"unified_key\": null,\n \"options\": {\n \"type\": \"inline\",\n \"entries\": [\n {\n \"label\": \"Site 1\",\n \"id\": \"FXrER44xubBqA9DLgZ3PFNNx\",\n \"unified_value\": \"1\",\n \"remote_id\": \"site_1\"\n },\n {\n \"label\": \"Site 2\",\n \"id\": \"2rv75UKT2XBoQXsUb9agiTUm\",\n \"unified_value\": \"2\",\n \"remote_id\": \"site_2\"\n }\n ]\n }\n },\n \"keyNumbers\": {\n \"type\": \"array\",\n \"label\": \"Key Numbers\",\n \"required\": false,\n \"description\": \"Employee's key numbers\",\n \"unified_key\": null,\n \"min_items\": 2,\n \"max_items\": 5,\n \"item_type\": {\n \"type\": \"number\",\n \"label\": \"Key Number\",\n \"required\": false,\n \"description\": \"The number of the keys which belong to the employee\",\n \"unified_key\": null,\n \"min\": 0,\n \"max\": 99\n }\n }\n }\n }\n }\n}\n```"
tags:
- Unified HRIS API
parameters:
- in: header
name: X-Integration-Id
schema:
type: string
description: ID of the integration you want to interact with.
example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
required: true
responses:
'200':
description: GET /hris/employees/form Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/GetHrisEmployeesFormPositiveResponse'
examples:
example1:
value:
status: success
data:
properties:
firstName:
label: First Name
required: true
description: Employee's first name
unified_key: first_name
type: text
min_length: 1
max_length: 100
reg_exp: null
startDate:
label: Start Date
required: true
description: Employee's start date
unified_key: start_date
type: date
workLocation:
label: Work Location
required: false
description: Employee's work location
unified_key: null
type: object
properties:
site:
label: Site
required: true
description: Employee's site
unified_key: null
type: single_select
options:
type: inline
entries:
- id: FXrER44xubBqA9DLgZ3PFNNx
label: Site 1
unified_value: '1'
remote_id: site_1
- id: 2rv75UKT2XBoQXsUb9agiTUm
label: Site 2
unified_value: '2'
remote_id: site_2
keyNumbers:
label: Key Numbers
required: false
description: Employee's key numbers
unified_key: null
type: array
item_type:
label: Key Number
required: false
description: The number of the keys which belong to the employee
unified_key: null
type: number
min: 0
max: 99
min_items: 2
max_items: 5
warnings:
- message: This is an example warning!
default:
$ref: '#/components/responses/ErrorResponseHRIS'
post:
operationId: PostHrisEmployeesForm
summary: Create employee with form
description: "Create an employee, based on the form schema.\n\n<Note>\n This endpoint requires the permission **Create and manage employees** to be enabled in [your scope config](/scopes).\n</Note>\n\n### Example Request Body\n\n```json\n{\n \"properties\": {\n \"firstName\": \"John\",\n \"startDate\": \"2025-01-01\",\n \"workLocation\": {\n \"site\": \"8e422bf8cav\",\n \"keyNumbers\": [\n 142,\n 525,\n 63\n ]\n }\n }\n}\n```"
tags:
- Unified HRIS API
parameters:
- in: header
name: X-Integration-Id
schema:
type: string
description: ID of the integration you want to interact with.
example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
required: true
requestBody:
description: POST /hris/employees/form Request body
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisEmployeesFormRequestBody'
examples:
example1:
value:
properties:
firstName: John
startDate: '2025-01-01'
workLocation:
site: 8e422bf8cav
keyNumbers:
- 142
- 525
- 63
responses:
'200':
description: POST /hris/employees/form Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/PostHrisEmployeesFormPositiveResponse'
examples:
example1:
value:
status: success
data:
id: 26vafvWSRmbhNcxJYqjCzuJg
remote_id: '12345'
prehire:
remote_id: null
warnings:
- message: This is an example warning!
default:
$ref: '#/components/responses/ErrorResponseHRIS'
/hris/employees/{employee_id}:
patch:
operationId: PatchHrisEmployeesEmployeeId
summary: Update employee
description: "Update an employee.\n\n<Note>\n This endpoint requires the permission **Create and manage employees** to be enabled in [your scope config](/scopes).\n</Note>\n\n### Example Request Body\n\n```json\n{\n \"employee_id\": \"BkgfzSr5muN9cUTMD4wDQFn4\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"work_email\": \"john.doe@acme.com\",\n \"ssn\": \"555-32-6395\",\n \"tax_id\": \"12 345 678 901\",\n \"gender\": \"MALE\",\n \"marital_status\": \"MARRIED\",\n \"date_of_birth\": \"1986-01-01\",\n \"start_date\": \"2020-04-07\",\n \"termination_date\": \"2022-05-20\",\n \"job_title\": \"In
# --- truncated at 32 KB (530 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kombo/refs/heads/main/openapi/kombo-unified-hris-api-api-openapi.yml