# Overriding Unified API mappings > Source: https://truto.one/docs/guides/unified-apis/override/ 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 level (applies to only that specified integrated account) or Environment level (applies to multiples integrated accounts in that environment). 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 environment unified mapping overrides if available or base mapping from the Unified API to the raw API response (`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. ![Override Flowchart](https://docs-assets.truto.one/overrides-flowchart.png) ## How to specify an override for an Integrated account Let's take an example of HiBob, where we want to specify an override to get the `date_of_birth` for an employee and adding a query_param `name`. 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, ```bash curl --location --request PATCH 'https://api.truto.one/integrated-account/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "unified_model_override": { "hris": { "employees": { "list": { "query_mapping": "{ \"fullName\": query.name }", "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](https://app.truto.one/unified-apis/available/0477048a-f24b-4ad6-ad5b-5eaf15437d19) in the UI. - `employees` This is the resource you want to specify the override for. - `list` The overridden method - `query_mapping` Since we want to add query_param `name` to filter the results based on the name input, we specify the `query_mapping` which is a [JSONata](https://docs.jsonata.org/overview) expression. `name` is mapped to the query parameter `fullName` which is accepted by the HiBob API. - `response_mapping` Since we want to change the response, we specify the `response_mapping` which is a [JSONata](https://docs.jsonata.org/overview) 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](https://truto.one/docs/api-reference/unified-hris-api/employees/list) API request for the integrated account and it should return you the data with `date_of_birth` added to it. ## How to specify an override for an Environment Overriding Unified API mappings in Truto allows you to customize how data is translated between your systems and the Unified API. Follow these steps to override and adjust API mappings according to your environment and requirements: ### 1. Navigate to the Unified API Mapping - Go to the **Installed Unified API** section in your Truto dashboard. - Locate and select the **Mapping** tab. - From the list of available integrations, choose the one you want to modify. - Identify the specific API method you wish to override and click on the **pencil icon** next to it. ![Edit Mapping](https://docs-assets.truto.one/overriding-unified-api-screen.png) ### 2. Open the Mapping Modal Clicking the pencil icon opens a modal window containing various mapping configurations. Inside this modal, you will see separate sections for: - **Query Mapping** - **Request Body Mapping** - **Response Mapping** - **Error Mapping** - **Request Header Mapping** - **Response Header Mapping** ![Mapping Modal](https://docs-assets.truto.one/overriding-mappings-modal.png) Alterntaively, you can edit the mappings altogether by toggling the Code view. It opens up a `YAML` configuration that looks like - ![Mapping Modal Code View](https://docs-assets.truto.one/code-view-mapping.png) ### 3. Modify and Override the Mappings - **Change the Mappings:** - **Delete Fields:** Remove any fields that are not relevant to your integration needs. - **Add Extra Fields:** Insert new fields or parameters as necessary to tailor the request, response, headers, or error handling. - **Modify Existing Fields:** Adjust the field structure, data types, or `JSONata` transformation logic to align with your specific use case. ## How to specify an override for an Environment thorough API 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 installed unified model ID by specifying the name of unified_model in the following API request ```bash curl --location 'https://api.truto.one/environment-unified-model?unified_model.name=' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' ``` 2. Make a PATCH request on the installed unified model resource with the override details. For the example mentioned before, you'll have to make the following API request, ```bash curl --location --request PATCH 'https://api.truto.one/environment-unified-model/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "override": { "resources": { "employees": { "integration_mapping": { "hibob": { "list": { "query_mapping": "{ \"fullName\": query.name }", "response_mapping": "{ \"date_of_birth\": response.personal.shortBirthDate }" } } } } } } }' ``` The request body contains the following, - `override` This is the object which specifies the overrides - `resources` This is the object which specifies the overrides for multiple resources. - `employees` This is the resource you want to specify the overrides for. - `integration_mapping` Since we want to add the overrides for integration, we specify `integration_mapping` which is an object. - `hibob` This is the integration name you want to specify the overrides for. - `list` The overridden method - `query_mapping` Since we want to add query_param `name` to filter the results based on the name input, we specify the `query_mapping` which is a [JSONata](https://docs.jsonata.org/overview) expression. `name` is mapped to the query parameter `fullName` which is accepted by the HiBob API. - `response_mapping` Since we want to change the response, we specify the `response_mapping` which is a [JSONata](https://docs.jsonata.org/overview) 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](https://truto.one/docs/api-reference/unified-hris-api/employees/list) API request for the integrated accounts in the environment and it should return you the data with `date_of_birth` added to it for all of the integrated accounts in the specified environment. ## Bindings available to use in response_mappings Bindings are the data that are sent in the Unified API call, which can be used in response_mappings to apply overrides as per your needs. - `response` This is the raw API response returned by the API call. ``` { "response": { "personal": { "shortBirthDate": "1990-01-01" } } } ``` - `rawQuery` This is the object that contains the raw query parameters sent in the Unified API request. ``` { "fullName": rawQuery.name } ``` - `query` This is the object which specified the query params after mapping is applied as needed by the integration. ``` { "fullName": query.name } ``` :::callout{type="info"} Consider an example of query_mapping where the contact resource is mapped to `person_id` in the following way - ``` { "person_id": rawQuery.contact.id } ``` Now, if you need to map the contact resource in the response_mapping, you can do in the following ways - ``` { "contact": { "id": query.person_id } } ``` or ``` { "contact": { "id": rawQuery.contact.id } } ``` ::: - `body` This is the object that contains the body sent in the Unified API request. ``` { "fullName": body.name } ``` - `context` This is the object that contains all the variables stored in your Integrated account. ``` { "fullName": context.name } ``` Read more about [Bindings](/docs/guides/unified-apis/mapping-bindings) ## Available JSONata bindings in mappings JSONata methods are lifesavers while writing overrides for transforming the raw API response to the Unified API response schema. You can refer to Truto [JSONata](https://www.npmjs.com/package/@truto/truto-jsonata#custom-functions) to know more about the methods supported.