Learn how to create employee records in connected HRIS via Kombo.
Flowcharts of Workflow
Fetching the Form Schema
GET
https://api.kombo.dev/v1/hris/employees/formResponse:You’ll receive a JSON schema describing required fields, data types, labels, validation rules, and unified keys. Below is more information on how this schema is built.Note:The schema fields you receive are different for every HRIS and often even by instance. (e.g. firstName
, startDate
, workLocation
in the example response)Auto-fill Standard Fields via Unified Keys
first_name
and last_name
– which can automatically be pre-populated if the data already exists within your ATS; for that, the unified_key
property can be used, which is included on standard fields within the schema retrieved in the previous step.unified_key
:
first_name
or start_date
) if the data is already available in your ATS.Add Field Mapping (highly recommended, but optional)
first_name
and last_name
– which can automatically be pre-populated if the data already exists within your ATS; for that, we use the unified_key
.However, an individual employer might also have less common or custom fields that are required to create an employee record in their specific HRIS instance. For example, a travel-related company might have a field for nationality
configured in their HRIS, which they require to create an employee record (this field would be included in the form schema retrieved in the previous step).nationality
field returned in the HRIS form schema.We recommend providing your users the option to manually map ATS fields to HRIS fields via an intuitive UI.Guidance for UI Implementation
first_name
or start_date
if already available in your ATS.Example: Field Mapping UI
Capturing Any Missing Data (highly recommended, but optional)
Guidance for UI Implementation
first_name
or start_date
if already available in your ATS. You can also consider not displaying pre-populated fields at all, for a simplified UI/UX.Example: Missing Data Capture
Example: Missing Data Capture
Submitting Employee Data
POST
https://api.kombo.dev/v1/hris/employees/formRequest:Submit data matching the retrieved schema format to create an employee record.How it works:workLocation
in the example request snippet), include the corresponding sub-objects or arrays.Text
Number
Date
YYYY-MM-DD
.Single Select
employees
or departments
. For this case, please submit the ID as the selected value.Multi Select
employees
or departments
. For this case, please submit the IDs as the selected values.It is possible to have a minimum and maximum amount of items.Checkbox
Object
Array
File
"required": true
must be provided.workLocation
) is submitted, then its required properties (like site
) must be provided:workLocation
isn’t submitted, then the subfield requirement is bypassed.GET /employees/form
endpoint.Important Notes
Example: Dashboard Form Preview