Skip to content

Overriding Unified API mappings on an Integrated account

To support use cases where some of your customers might be using a specific custom fields for a resource, you can override the Unified API mappings on an Integrated account. This will allow you to map the custom fields to the Unified API fields.

How overrides are applied

Overrides only need to specify the mappings that you need to change or add or remove.

  1. Truto applies the base mapping from the Unified API to the remote_data.
  2. Overrides from the integrated account are applied to the same remote_data.
  3. If there are any attributes returned from Step 2 which are also returned from Step 1, then they are overwritten. Any new attributes from Step 3 are added to the unified API response.

How to specify an override

Let's take an example of HiBob, where we want to specify an override to get the date_of_birth for an employee.

To do this,

  1. Get the integrated account ID from the UI or the API where you want to apply the override.
  2. Make a PATCH request on the integrated account resource with the override details.

For the example mentioned before, you'll have to make the following API request,

curl --location --request PATCH '<integrated_account_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_api_key>' \
--data '{
    "unified_model_override": {
        "hris": {
            "employees": {
                "list": {
                    "response_mapping": "{ \"date_of_birth\": response.personal.shortBirthDate }"

The request body contains the following,

  • unified_model_override This is the object which specifies the overrides
    • hris This is the name of the Unified Model. You can find this on the Unified Model details page in the UI.
    • employees This is the resource you want to specify the override for.
    • list The overridden method
    • response_mapping Since we want to change the response, we specify the response_mapping which is a JSONata expression. The remote_data is present in response object within the JSONata expression.

Now you can go ahead and make the LIST /unified/hris/employees API request for the integrated account and it should return you the data with date_of_birth added to it.