Custom Fields

​

What is a custom field

All HR systems are inherently limited in the number of standard fields they can offer. This can be a problem if you need to store additional information about your employees.

Initially, HR systems started adding an increasing number of standard fields to their systems. This quickly became a problem. As the number of fields grew to hundreds, the systems became very hard to maintain.

Custom fields are a way to solve this problem. They allow you to store any data you want about your employees. By now most HR systems have adopted this concept and offer custom fields.

​

How to use custom fields

We offer a simple way to read custom fields from your HR system. The first step is to create a custom field in your HR system.

​

Personio

Let’s take Personio as an example.

Under Settings > Employee Information you can easily add new attributes or entire new sections to your employee profiles. We will add a new attribute called “Favorite Color” to the “Public Profile” section.

If we now go to the profile of an employee, we can see the new field. Let’s set a value for it.

In the case of Personio we need to let the API key know that we want to expose the new custom field. Just go to Settings > API Credentials and click on the API key you used to connect to Kombo. Then, open the “Readable employee attributes” section and select the new custom field.

Don’t forget to click save and that’s it!

​

Setting up custom fields in Kombo

Before we setup the custom field in Kombo, let’s talk about how you will receive the data.

​

Data format

Each model that supports custom fields has a custom_fields attribute. This attribute is a JSON object that contains all custom fields. You can define a name for the custom field in Kombo, which will be used as the key in the JSON object.

We will then allow you to map any custom field from an integration to that custom field. This allows you to unify the data from different integrations. Let’s say you have a customer with a custom field called “Favorite Color” and another customer with a custom field called “Favourite Colour”. You can map both of them to the same custom field in Kombo, so that you can always access the data in the same way.

​

Setting up the custom field

Now that we have set up the custom field in Personio, we can go to Kombo and set up the custom field there.

Open the Dashboard and click on “Configuration” in the sidebar, then on “Custom Fields” tab. There you can create a new custom field. Let’s call it “fav_color”.

Here you can see how many integrations use this field and all the aliases that you have defined for this field. Aliases are used to automatically map custom fields from integrations to your custom field. You can add as many aliases as you want. When an alias matches a custom field from an integration, it will be automatically mapped to your custom field. This allows you to largely automate the process of mapping custom fields.

If you want to map a custom field manually, you need to open the overview for that integration. We will only discover custom fields after a sync ran, so make sure to click the “Sync now” button. After the sync finished, you can open the custom field dropdown and select the custom field you want to map.

Don’t forget to click “Update mappings” to save your changes. One final sync and that’s it! You can now access the custom field in the API.

​

Accessing custom fields in the API

When you query the API, you will receive the custom fields in the custom_fields attribute. In this case we query the GET /employees endpoint. The type of a custom field is always the type that is returned by the underlying API (i.e. it’s not always string but can be a number or even object too).

{
  "status": "success",
  "data": {
    "results": [
      {
        "...": "...",
        "custom_fields": {
          "fav_color": "blue"
        }
      }
    ]
  }
}