​
Overview

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.

Get employee form

Get the form definition that you can render on your frontend.

Create employee

Post the data that you collected from the form to create an employee.

  • Consistent data structure across diverse/customized HR systems.
  • Automated field mapping associates fields in ATS with fields in HRIS, reducing manual efforts and errors.
  • Consistent and Validated Data: Ensures data is accurate, complete, and validated, reducing onboarding errors.

​
Implementation Steps

1

Fetching the Form Schema

Endpoint:

GET https://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)

Example Response Snippet:

Example Result
{
  "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
      },
      "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": "Office",
                },
                {
                  "id": "2rv75UKT2XBoQXsUb9agiTUm",
                  "label": "Warehouse",
                }
              ]
            }
          },
          "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
          }
        }
      }
    }
  }
}
2

Auto-fill Standard Fields via Unified Keys

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
}

Supported Unified Keys include:

Example Result
  'first_name',
  'last_name',
  'date_of_birth',
  'gender',
  'home_address.city',
  'home_address.country',
  'home_address.state',
  'home_address.street_1',
  'home_address.street_2',
  'home_address.zip_code',
  'job_title',
  'legal_entity_id',
  'location_id',
  'mobile_phone_number',
  'nationality',
  'start_date',
  'work_email',
  'private_email',

Unified Values for Gender Mapping:

Example Result
  'MALE',
  'FEMALE',
  'NON_BINARY',
  'NOT_SPECIFIED',

After fetching the schema:

  • 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).

Example Result
"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.

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:

  1. Do not have the specific data available within your ATS
  2. Require user input to decide on the correct value

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 Result
"dateOfBirth": {
                "label": "Date of Birth",
                "required": true,
                "description": "Date of birth of the employee.",
                "unified_key": "date_of_birth",
                "type": "date"
            }

5

Submitting Employee Data

Endpoint:

POST https://api.kombo.dev/v1/hris/employees/form

Request:

Submit data matching the retrieved schema format to create an employee record.

How it works:

  • All required fields from the schema retrieved in the GET call must be included
  • The POST payload mirrors the GET schema’s nested structure.
  • Data is organized under the properties key.
  • For nested fields (like workLocation in the example request snippet), include the corresponding sub-objects or arrays.

Example Request Snippet:

Example Result
{
   "properties":{
      "firstName":"UserFirst",
      "startDate":"2025-01-15",
      "workLocation":{
         "site":"ad67886e26d",
         "keyNumbers":[
            2,
            44,
            5
         ]
      }
   }
}

​
Field Types & Validation

Our API supports several field types, each with its own validation rules. Below are summarized examples:

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).

​
Additional Information

  • Fields marked "required": true must be provided.
  • Optional objects, if included, must have their required subfields completed.

Example Scenario:

If an optional object (workLocation) is submitted, then its required properties (like site) must be provided:

Example Result
"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": "Office",
                },
                {
                  "id": "2rv75UKT2XBoQXsUb9agiTUm",
                  "label": "Warehouse",
                }
              ]
            }
          }
        }
      }

If workLocation isn’t submitted, then the subfield requirement is bypassed.

​
Summary

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.