Creating Employees (v2)

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.

Benefits

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.

High-level Workflow

To create an employee:

Connect HRIS – Ensure an HRIS connection is set up via Kombo Connect.
Fetch Schema – Retrieve fields required by the connected HRIS to create an employee.
Map Fields & Capture Data – Pre-populate fields from your ATS data and capture any missing data in your UI.
Submit Employee Data – Push validated employee data to create employee record in connected HRIS.

Flowcharts of Workflow

Relevant API endpoints

Get employee form

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

Create employee with form

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

Implementation Steps

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 Response

{
  "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
          }
        }
      }
    }
  }
}

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:

Unified Keys

  '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',
  'yearly_salary',

Unified Values for Gender Mapping:

Unified Values

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

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

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

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

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.

Example Field

"department": {
                "label": "Department",
                "required": true,
                "description": "Department of the employee.",
                "unified_key": null,
                "type": "single_select",
                "options": {
                    "type": "referenced",
                    "link": "https://api.kombo.dev/v1/hris/groups?types=DEPARTMENT"
                }
            }

Example: User Input Required

Guidance for UI Implementation

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:

Text

Used for any textual input (e.g., first names, last names).

Schema

Schema

{
  type: "text";
  label: string;
  required: boolean;
  description: string | null;
  unified_key: string | null;
  min_length: number | null;
  max_length: number | null;
}

Post Example

Post Example

{
  "position": "Data Engineering"
}

Number

Used for numeric values such as ages or IDs.

Schema

Schema

{
  type: "number";
  label: string;
  required: boolean;
  description: string | null;
  unified_key: string | null;
  min: number | null;
  max: number | null;
}

Post Example

Post Example

{
  "keyCard": 4
}

Date

Used for date entries (e.g., employee start dates). The expected format is YYYY-MM-DD.

Schema

Schema

{
  type: "date";
  label: string;
  required: boolean;
  description: string | null;
  unified_key: string | null;
}

Post Example

Post Example

{
  "hireDate": "2025-01-25"
}

Single Select

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 or departments. For this case, please submit the ID as the selected value.

Schema

Schema

{
      type: 'single_select'
      label: string
      required: boolean
      description: string | null
      unified_key: string | null
      options:
        | {
            type: 'inline'
            entries: {
              label: string
              id: string
              unified_value: string
            }[]
          }
        | {
            type: 'referenced'
            link: string
          }
    }

Post Example

Post Example

{
  "department": "2rv75UKT2XBoQXsUb9agiTUm"
}

Multi Select

Allows selection of multiple options from a predefined list. Please submit the values of the items.

It is possible to have a minimum and maximum amount of items.

Schema

Schema

{
      type: 'multi_select'
      label: string
      required: boolean
      description: string | null
      unified_key: string | null
      options:
        | {
            type: 'inline'
            entries: {
              label: string
              id: string
              unified_value: string
            }[]
          }
        | {
            type: 'referenced'
            link: string
          }
    }

Post Example

Post Example

{
  "supervisors": ["2rv75UKT2XBoQXsUb9agiTUm","FXrER44xubBqA9DLgZ3PFNNx"]
}

Checkbox

A simple checkbox used for binary choices

Schema

Schema

{
  type: "checkbox";
  label: string;
  required: boolean;
  description: string | null;
  unified_key: string | null;
}

Post Example

Post Example

{
  "hasCar": true
}

Object

Used for nested fields or grouped data. Each property within the object is defined using a field type.

Schema

Schema

{
  type: "object";
  label: string;
  required: boolean;
  description: string | null;
  unified_key: string | null;
  properties: {
    [key: string]: FieldObject;
  };
};

Post Example

Post Example

{
   "workLocation":{
      "city":"Berlin",
      ...
   }
}

Array

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.

Schema

Schema

{
  type: "array";
  label: string;
  required: boolean;
  description: string | null;
  unified_key: string | null;
  min_items: number | null;
  max_items: number | null;
  item_type: FieldObject;
};

Post Example

Post Example

Object Example:
{
   "<key>":[
      {
         "<subKey>":"FieldObjectValue"
      },
      {
         "<subKey>":"FieldObjectValue"
      }
   ]
}

Text Example:
{
   "tags":[
     "Test1", "Test3", "Test4"
   ]
}

File

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.

Schema

Schema

{
  type: "file";
  label: string;
  required: boolean;
  description: string | null;
  unified_key?: string | null;
  file_restrictions: {
      accepted_mime_types: string[];
      max_file_size?: number | null;
    }
}

Post Example

Post Example

{
  "CV": "UEsDBBQAAAgIAK...."
}

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.

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.

Kombo uses a property called unified_key to standardize common fields between ATS and HRIS systems, allowing automatic data mapping.

Example:

ATS provides first name data as:
Example
```
{ "first_name": "Jane" }
```
Kombo automatically maps this into the HRIS’s expected field.

Supported Unified Keys include:

Unified Keys

  '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',
  'yearly_salary',

Unified Key Values for Gender Mapping:

Unified Key Values

  'MALE',
  'FEMALE',
  'NON_BINARY',
  'NOT_SPECIFIED',

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.

Dashboard Form Preview

The Kombo Dashboard provides a convenient way to preview the employee form for connected HRIS systems:

Developer Preview Tool – Allows you to see exactly what fields you’ll receive through the GET /employees/form endpoint.
Visual Reference – Shows how the form could look when rendered in a frontend application.
Testing Environment – Helps you understand where created employees will appear in the HRIS and verify field mappings.

Important Notes

Example: Dashboard Form Preview

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.

General

Features

Guides

HRIS API Reference

General API Reference

DATEV

Creating Employees (v2)

Overview

Benefits

High-level Workflow

Relevant API endpoints

Get employee form

Create employee with form

Implementation Steps

Field Types & Validation

Additional Information

Dashboard Form Preview

Summary

General

Features

Guides

HRIS API Reference

General API Reference

DATEV

​Overview

​Benefits

​High-level Workflow

​Relevant API endpoints

Get employee form

Create employee with form

​Implementation Steps

​Field Types & Validation

​Additional Information

​Dashboard Form Preview

​Summary

Overview

Benefits

High-level Workflow

Relevant API endpoints

Implementation Steps

Field Types & Validation

Additional Information

Dashboard Form Preview

Summary