Kombo’s Create Employee feature streamlines onboarding by enabling ATS platforms to automatically create employee records in connected HRIS.Rather than manually entering data, this integration dynamically identifies and retrieves each HRIS’s specific requirements for creating employee records (the data schema), letting your platform easily send correctly formatted employee data directly from the ATS to the HRIS–creating new employee records.
Endpoint:GEThttps://api.kombo.dev/v1/hris/employees/form Response: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)
Hiring into a position or requisition? Pass an optional
staffing_entity_id query parameter to scope the form — whenever possible
form fields will be pre-filtered to the values linked to the selected staffing entity.
This includes Kombo unisversal fields like department or location, but also deeply
tool specific fields like payGroup from UKG Pro.
See the staffing entities in create employee guide
for the full workflow.
To create an employee record, all fields required by the HRIS must be populated appropriately and submitted. Most HRIS will require some similar standard fields such as 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.
Example:
If an HRIS wants a property with the following key:
{ "FirstNameOfEmployee": "Jane" }
Kombo automatically maps this property to the unified_key:
"FirstNameOfEmployee":{ "label":"First Name", "required":true, "description":"The first name of the employee", "unified_key":"first_name", "type":"text", "min_length":null, "max_length":null}
Automatically populate fields with unified keys (e.g. first_name or start_date) if the data is already available in your ATS.
3
Add Field Mapping (highly recommended, but optional)
To create an employee record, all fields required by the HRIS must be populated appropriately and submitted. Most HRIS will require some similar basic fields such as 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).
Required Field Example
"nationality": { "label": "Nationality", "required": true, "description": "Nationality of the employee.", "unified_key": null, "type": "text", "min_length": null, "max_length": null },
In this example, if you already have data for a person’s nationality stored within your ATS (e.g. because it was captured as part of a job application), then the ATS field with the nationality value can be mapped to the 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
Automatically populate fields such as first_name or start_date if already available in your ATS.
Field Mapping UI: For HRIS admins, provide an intermediate mapping step after the HRIS connection, that verifies and adjusts the correspondence between ATS data fields and the HRIS schema.
Responsive Design: Ensure the form displays correctly on both desktop and mobile devices.
Example: Field Mapping UI
4
Capturing Any Missing Data (highly recommended, but optional)
There might be situations in which an employer’s HRIS might require specific fields to be populated, where you either:
Do not have the specific data available within your ATS
Require user input to decide on the correct value
Example 1: Data Unavailable in ATS
Example 2: User Input Required
For example, an employer might have a field for dateOfBirth configured in their HRIS, which they require to create an employee record (these fields would be included in the form schema retrieved in step 1).In the example of the dateOfBirth field, you might not have data stored within the ATS that you can map into this field. Therefore, you’d want to expose an input field to the user while creating the employee record, prompting the user to enter this missing information, required by the HRIS.
Example Field
"dateOfBirth": { "label": "Date of Birth", "required": true, "description": "Date of birth of the employee.", "unified_key": "date_of_birth", "type": "date" }
Example: Data Unavailable in ATS
For example, an employer might have a field for department configured in their HRIS, which they require to create an employee record.In the example of the department field, you might have the relevant department options stored within your ATS. But it might be necessary for the ATS user (e.g. an HR manager) to decide which specific department should apply to this employee. In this case, you could display an input field to the user, with dropdown options to choose the correct department.For single_select and multi_select fields, the options can be set as referenced rather than provided inline. This means that the selectable options won’t be included directly in the form; instead, you’ll need to query them separately from Kombo or your database.This method is commonly used for scenarios such as selecting supervisors (employees) or referencing departments. To support this, we provide you with a query link from the Kombo model, which you can use to retrieve and display relevant information—such as the department name—and return the corresponding ID as the selected value or values.
Dynamically generate fields to display: Parse the schema to render appropriate inputs (e.g., text boxes, date pickers, dropdowns, checkboxes).
Auto-populate fields when possible: Pre-populate fields such as 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.
id – The Kombo ID of the created employee record. This will be null if only a pre-hire was created.
remote_id – The raw ID from the remote HRIS system. This is only populated when id is set (i.e., when a full employee was created). For pre-hires, use the prehire object instead.
prehire – An object containing the temporary prehire information from the remote system. Includes a remote_id field with the prehire ID (or null if there is no pre-hire). This ID may change or become invalid when the prehire becomes a full employee. The remote_id is only populated when id is null.
Use Case: HRIS systems with multi-step onboarding workflows. Some return a pre-hire identifier (e.g., Paylocity, Workday), while others don’t return any identifier (e.g., HiBob’s Hire API).
Our API supports several field types, each with its own validation rules. Below are summarized examples:
Text
Used for any textual input (e.g., first names, last names). Supports length constraints via min_length/max_length and pattern validation via reg_exp (regular expression).
When a field includes both length constraints and regex patterns (as defined by the API), all validations must pass. Ensure your input data meets both the length requirements and matches the specified regex pattern.
Allows selection of a single option from a predefined list, if the type is options. Please submit the value of the Item.A link is provided for type reference, from which you can query the specific options. For example, this link can be used to get all employees, departments, or staffing-entities (e.g. positions or requisitions). For this case, please submit the ID as the selected value.
Remote ID SupportInline single-select fields support submitting remote IDs directly using the remote: prefix:
Remote ID Example
{ "department": "remote:dept-123"}
This allows you to use the original remote system IDs instead of Kombo IDs.
Only inline single-select fields support this format. Referenced fields require Kombo IDs.
Multi Select
Allows selection of multiple options from a predefined list. Please submit the values of the items.A link is provided for type reference, from which you can query the specific options. For example, this link can be used to get all employees, departments, or staffing-entities (e.g. positions or requisitions). For this case, please submit the IDs as the selected values.It is possible to have a minimum and maximum amount of items.
Used when multiple items of the same type are expected, such as a list of values. You can define the minimum and maximum number of items. Please note that the item_type can also be an object.
Used for uploading files. Restrictions, such as accepted MIME types and the maximum allowed file size, can be specified. Please submit the data as a Base64 string.
For each type, ensure client-side and server-side validation is in place (e.g., ensuring required fields are provided, input adheres to defined constraints, and clear error messages are surfaced).
When a single_select or multi_select field uses options.type: "referenced", the link points to a Kombo HRIS endpoint you can call to retrieve the selectable entries. The selected value(s) you submit back must be the Kombo id of the chosen record(s).The following Kombo data models can appear as reference targets in the employee form. The exact link — including any pre-applied query parameters — is always provided in the form schema, so you should use it as-is rather than constructing it yourself.
Recommended: sync referenced data ahead of time instead of fetching it on
the fly.All of the models below (employees, legal entities, locations, groups, staffing
entities) are regular Kombo data models that you should already be syncing
into your own database as part of your HRIS integration. When rendering the
employee form, it’s generally better to populate the select options from
your synced copy rather than calling the referenced link in real time:
Scale: Some of these lists can be very large (thousands of employees,
hundreds of positions, etc.). Fetching them on every form render is slow
and can hit pagination limits.
UX: You can enrich the options with additional context from your own
data (e.g. department, job title, location), provide proper search/typeahead,
and cache them across sessions.
Only fall back to calling the referenced link directly if you don’t already
have the data synced, or for small/static reference lists where the extra
request is negligible.
Employees
Used for fields that reference another employee, most commonly supervisors/managers.
Used for fields that reference the legal employer / sub-company the employee should be attached to. Standard fields like legal_entity_id use this model.
Used for fields that reference an organizational group such as a department, team, or cost center. Kombo models all of these under the unified groups endpoint and exposes the sub-type via the types query parameter.
Link:GET /v1/hris/groups (typically pre-filtered, e.g. ?types=DEPARTMENT, ?types=TEAM, or ?types=COST_CENTER)
If multiple group sub-types are relevant (e.g. the HRIS exposes both
departments and cost centers as separate fields), you’ll receive multiple
referenced fields, each with its own pre-filtered link.
Staffing Entities (Positions, Requisitions, Jobs)
Used for fields that target a specific hiring slot the employee is being hired into. See the Staffing entities feature page for a full overview of the model.
Link:GET /v1/hris/staffing-entities (optionally pre-filtered by model_types and/or statuses)
The pre-applied filters reflect what is meaningful for the connected HRIS
(for example, only OPEN_UNLIMITED jobs, or only REQUISITION records).
Use the link as returned in the schema.
Client Side:Validate that all required fields are provided, validate formats (e.g., dates, numeric ranges), and provide inline validation messages.
Server Side:Ensure the API returns clear error responses (400 for validation errors, 500 for server issues) and include guidance on resolving common errors.
Although Create Employee is a write feature, it often needs to read some information to work. Take a look at the following scenarios:
The form schema includes a manager field that references another employee’s ID.You may want to access the list of employees in order to render a select including the names of all employees (or better: only the managers), with their names mapped to IDs.
The form schema includes a field that references a staffing entity (e.g. a position or requisition) that the employee should be hired into.This requires access to the list of staffing entities, which you can query via the GET staffing entities endpoint. The referenced link returned in the form schema will point to this endpoint (optionally pre-filtered by model_types and/or statuses).
Real-world example
Paylocity HRIS allows defining the costCenter1, costCenter2, and costCenter3 fields when creating an employee.Their values reference the cost centers, which are a part of Kombo’s Groups data model.In order to access them, make sure that you enable this data model in the Scope configuration.
A quick way to check specifically which scopes are required/useful for create employee, is to visit the integration-specific documentation and look for Supported Features & Coverage → Create Employee with Form.Here are a few examples:
By implementing Kombo’s Create Employee functionality, your ATS platform simplifies employee onboarding by dynamically adapting to any HRIS schema, automating data mapping, and ensuring reliable data submission.
