> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Fields

> Learn how to use integration fields to read additional data properties from your customer's systems.

<Warning>
  The Integration Fields API was built for a very specific niche use case. This
  is likely not what you want to use. See [Custom Fields](./custom-fields)
  instead.
</Warning>

## 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](#selecting-an-integration-field).

### View available integration fields

To list which integration fields are available for a specific integration, you should use our [GET integration-fields](../v1/get-integrations-integration-id-integration-fields) endpoint.

Example response:

```JSON theme={null}
{
    "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](https://app.kombo.dev/scope-config).

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

### Selecting an integration field

To select an integration field to be passed through, use the [PATCH integration-fields](../v1/patch-integrations-integration-id-integration-fields-integration-field-id) endpoint.

An example payload would look like this:

```JSON theme={null}
{
    "enable_passthrough": true
}
```

Example response:

```JSON theme={null}
{
    "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](/hris/v1/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).

```JSON theme={null}
{
  "status": "success",
  "data": {
    "results": [
      {
        "first_name": "Frank",
        ...,
        "integration_fields": [
          {
            "id": "123AbcDEFG4hijK5Lmn67OPq",
            "key": "dynamic_5487319",
            "type": "CUSTOM",
            "value": "National Health",
            "label": "Name of health insurance"
          }
        ],
        ...
      }
    ]
  }
}
```