Integration Fields
Learn how to use integration fields to read additional data properties from your customer’s systems.
What is an integration field
An integration field is a field returned from the raw response of the remote system.
Setting up integration fields in Kombo
Before we set up the integration field in Kombo, let’s talk about how you will receive the data.
Each model that supports integration fields has an integration_fields
attribute. This attribute is an Array of JSON objects that contains all selected integration fields. We will discuss how to select integration fields in a later step.
View available integration fields
To list which integration fields are available for a specific integration, you should use our GET integration-fields endpoint.
Example response:
{
"status": "success",
"data": {
"results": [
{
"id": "123AbcDEFG4hijK5Lmn67OPq",
"key": "dynamic_5487319",
"model": "hris_employees",
"type": "CUSTOM",
"label": "Name of health insurance",
"is_passthrough_enabled": false
},
...
]
},
"next_cursor": null
}
If your array is empty or does not contain the values that you are looking for, double check if “integration fields” is enabled for the specific model in your scope config.
Please note that this endpoint is paginated, featuring a default page size of
250 and a maximum page size of 2000 (specified via the page_size
parameter).
Selecting an integration field
To select an integration field to be passed through, use the PATCH integration-fields endpoint.
An example payload would look like this:
{
"enable_passthrough": true
}
Example response:
{
"status": "success",
"data": {
"id": "123AbcDEFG4hijK5Lmn67OPq",
"key": "dynamic_5487319",
"model": "hris_employees",
"type": "CUSTOM",
"label": "Name of health insurance",
"is_passthrough_enabled": true
}
}
After successfully enabling passthrough on an integration field, the next sync will collect the values for the selected field and save them. These values then become part of our API response as follows:
Getting integration fields as part of the API response
When you query the API, you will receive any selected integration fields in the integration_fields
attribute. In this case, we query the GET /employees endpoint.
The value of an integration field mirrors what is returned by the underlying API (i.e. it’s not always a string
but can be a number
or even an object
too).
{
"status": "success",
"data": {
"results": [
{
"first_name": "Frank",
...,
"integration_fields": [
{
"id": "123AbcDEFG4hijK5Lmn67OPq",
"key": "dynamic_5487319",
"type": "CUSTOM",
"value": "National Health",
"label": "Name of health insurance"
}
],
...
}
]
}
}