# Custom Field mapping Field mapping lets you extend the Unify response with properties that live outside the standard Unify Model, either a downstream API's own integration-specific field or a customer's own custom field, so you can access it the same way for every connector instead of parsing each raw response yourself. > Field Mapping is the process of defining how a property from an integration response should be mapped to the Unify response. ## Understanding API Fields A Unified API normalizes every downstream API's response into one consistent set of properties, so a single request to an Apideck endpoint returns the same shape regardless of which downstream API served it. Apideck's Unify Model applies that normalization to the Unified APIs. ![Unify integrations](/guides/field-mapping/unify-api-integrations.png) Apideck maps each downstream response's properties onto a common set of properties defined by the Unify Model, so the Unify response always exposes the same fields no matter which downstream API answered the request. That consistency has a tradeoff: the Unify response only contains the properties that are common across all downstream APIs in that category, so a field unique to one integration, or a field your customer defined themselves as a custom field, will not appear in the standard response unless you map it explicitly. Field mapping is how you add it. - [Understanding API Fields](#understanding-api-fields) - [Response fields](#response-fields) - [Custom fields](#custom-fields) - [Unified models](#unified-models) - [Mapping fields](#mapping-fields) - [Field mapping feature](#field-mapping-feature) - [Field mapping types](#field-mapping-types) - [Property mapping](#property-mapping) - [Custom field mapping](#custom-field-mapping) ### Response fields Every downstream API names, structures, and formats its response fields differently, even when two integrations return the same underlying data. The three CRM responses below show how the same kind of lead data appears across different CRMs, with different field names, structures, and even different date formats. _A SalesForce example response:_ ```json { "Id": "123", "LastName": "Doe", "FirstName": "Jane", "T_shirt_Size__c": "Medium", "LastReferencedDate": "2024-01-12T10:46:34.000+0000", "LeadSource": "Trade Show", "CreatedDate": "2019-07-09T19:35:03.000+0000" } ``` _A Hubspot example response:_ ```json { "id": "123", "properties": { "lastname": "Doe", "firstname": "Jane", "t_shirt_size": "Small", "lifecyclestage": "lead", "hs_analytics_first_timestamp": "1601666897728", "hs_analytics_first_visit_timestamp": "1601666897728" }, "createdAt": "2019-07-09T19:35:03.000+0000" } ``` _A Pipedrive example response:_ ```json { "data": { "id": "d2b4f0b0-6219-11eb-84bd-4b223d902a50", "first_name": "First", "last_name": "Last", "c692e0f0cc9f675d5b6219c3e16": "Small", "won_deals_count": 0, "related_won_deals_count": 0, "add_time": "2020-10-04 09:58:26" } } ``` The three responses above fall into three types of fields: - **Standard fields**: available in every integration, though with different names, casing, and data formats, like `id`, `first_name`, `last_name`, `created_at`. - **Integration fields**: specific to one integration's own data model, like `hs_analytics_first_timestamp` or `LastReferencedDate`. - **Custom fields**: created by the end user inside the integration itself, like `T_shirt_Size__c`, `t_shirt_size`, or `c692e0f0cc9f675d5b6219c3e16`. ### Custom fields Custom fields are fields the end user created themselves inside the integration, letting them store additional information alongside the integration's standard fields. Custom fields are returned as part of the integration's response. Depending on the integration, they can be nested in a dedicated object or sit directly on the root object. _An example for SalesForce, where custom fields are part of the root object, typically ending with `__c`:_ ```json { "Id": "123", "LastName": "Doe", "FirstName": "Jane", "T_shirt_Size__c": "Medium", "Assigned_CSM__c": "Tom S.", "Lifecycle_Stage__c": "Lead", "CreatedDate": "2019-07-09T19:35:03.000+0000" } ``` _An example from Hubspot, where custom fields are nested in the `properties` object, as any other field:_ ```json { "id": "123", "properties": { "lastname": "Doe", "firstname": "Jane", "t_shirt_size": "Small", "assigned_csm": "Kristof W.", "lifecyclestage": "lead" }, "createdAt": "2019-07-09T19:35:03.000+0000" } ``` _An example from Pipedrive, where custom fields are nested in the `data` object and have a unique key:_ ```json { "data": { "id": "d2b4f0b0-6219-11eb-84bd-4b223d902a50", "first_name": "First", "last_name": "Last", "add_time": "2020-10-04 09:58:26", "c692e0f0cc9f675d5b6219c3e16": "Lead", "c692e0f58789dfebb3adba15721": "Small", "e24805787eef64b08aafb6fa3d8": "Kristof W." } } ``` _An example from a CRM integration that has custom fields listed under `CustomFields` as an array of key/value pairs:_ ```json { "Id": "8750", "FirstName": "First", "LastName": "Last", "CustomFields": [ { "key": "TShirtSize", "value": "Small" }, { "key": "AssignedCSM", "value": "Tom S." } ] } ``` As the four examples above show, custom fields are never standardized across integrations: each one uses its own naming and structure for the same underlying user-created field. ### Unified models The Unify Model exists because every downstream API otherwise forces you to learn that API's own field names, casing, and data formats before you can build against it. Apideck applies the Unify Model to remove that per-integration knowledge requirement. ![Unify model - CRM Contact](/guides/field-mapping/unify-model.png) The Unify Model is a standardized set of fields available consistently across every integration within a category, such as CRM, Accounting, or HRIS. It abstracts each resource, such as a lead, contact, employee, folder, or file, into one set of standard fields with consistent naming, casing, and data formats across every integration in that category. ![Unify integrations](/guides/field-mapping/unify-api-integrations.png) The Unify Model supports a wide range of use cases on that consistent shape, including registering a new lead, updating a contact, and creating a new employee. ## Mapping fields The Unify API maps each integration's available fields onto the Unify Model automatically, so the response you receive is already in the unified shape without you writing per-integration transformation code. ![Unify mapping](/guides/field-mapping/unify-api-mapping.png) On each request, the Unify API validates the incoming request, transforms it into the specific parameters the target integration expects, sends it downstream, then transforms that integration's response back into the common Unify format before returning it to you. ## Field mapping feature Field mapping extends the Unify Model with additional properties, either an integration-specific field or a customer's own custom field, so that property is included in the Unify response going forward. It exists for the two cases the standard model doesn't cover: a property present in one integration's response but not part of the Unify Model, and a property your customer defined themselves as a custom field that only they know the name of. The Hubspot `lifecyclestage` property is an example of the first case: it's specific to Hubspot and not part of the Unify Model. ![Hubspot response](/guides/field-mapping/unify-field-mapping-raw.png) By mapping the field within Apideck, the `lifecyclestage` property will be included in the Unify response for all consumers that connect. ![Unify mapping](/guides/field-mapping/unify-field-mapping-vault.png) ![Unify response](/guides/field-mapping/unify-field-mapping-unify.png) If Unify is making multiple requests to the integration you (if you are an application owner) will have the option of selecting for which request you want to map the field. Changing the request will change the available fields. ![Unify response](/guides/field-mapping/field-mapping-request.png) For example Unify does multiple requests to `IRIS Cascade HR` connector to form Employees response, as seen above, you can select between the requests to select the field accordingly. ## Field mapping types Apideck supports two types of field mapping, distinguished by where they look for the source value: - **Property mapping:** will search for the source field in the _raw response_ of the integration - **Custom field mapping**: will search for the source field in the _Unify response_, in the list of `custom_fields`. ### Property mapping Property mapping maps a field from an integration's raw response to a field in the Unify response. It's used for a property that isn't part of the Unify Model but is present in that integration's own response. _Hubspot response with all Hubspot properties:_ ```json { "id": "551", "properties": { "assigned_csm": "Kristof W.", "associatedcompanyid": "4562962674", "createdate": "2020-10-02T14:48:17.728Z", "custom_field": "", "email": "e.earhart@noemail.com", "firstname": "Emilia", "hs_object_id": "551", "hubspot_owner_id": null, "jobtitle": "Pilot", "known_via": "Apideck", "lastmodifieddate": "2024-01-12T10:42:21.467Z", "lastname": "Earhart", "lifecyclestage": "lead", "phone": "+32470123323", "website": "https://lead.com" }, "createdAt": "2020-10-02T14:48:17.728Z", "updatedAt": "2024-01-12T10:42:21.467Z", "archived": false } ``` The `lifecyclestage` property above is not part of the Unify Model, but it is present in the raw Hubspot response, so it's a property-mapping candidate. Define a new field, "lifecycle_stage", on the Unify model first. ![Custom Field mapping - Create new field](/guides/field-mapping/admin-custom-mapping-create.png) Provide a unique "Key" and a descriptive "Name." Optionally, add a brief "Description." The "key" will be utilized in the API response. The next step, is to configure the mapping for the "lifecycle_stage" field for the Hubspot integration. ![Custom Field mapping - Select integration](/guides/field-mapping/admin-custom-mapping-integration.png) Since "lifecycle_stage" is a property of the Hubspot response, we need to configure a "property mapping". ![Custom Field mapping - Select mapping type](/guides/field-mapping/admin-custom-mapping-integration-type.png) Browse through the available Hubspot fields and select the "lifecyclestage" property. ![Custom Field mapping - Select matching response key from the integration](/guides/field-mapping/admin-custom-mapping-integration-mapping.png) Press Save to store the mapping for Hubspot. ![Custom Field mapping - Save the configured mapping](/guides/field-mapping/admin-custom-mapping-integration-mapped.png) The mapping is now configured for the Hubspot integration, and will be included in the Unify response. _Result: Unify response with `custom_mappings` property, containing the field mapping for the "lifecycle_stage" property._ ```json { "status_code": 200, "status": "OK", "service": "hubspot", "resource": "contacts", "operation": "one", "data": { "id": "551", "name": "Emilia Earhart", "first_name": "Emilia", "last_name": "Earhart", "title": "Pilot", "updated_at": "2024-01-12T10:42:21.467Z", "created_at": "2020-10-02T14:48:17.728Z", "custom_mappings": { "lifecycle_stage": "lead" } } } ``` For more details on how to configure a Property mapping, check out the [Field Mapping](https://help.apideck.com/en/articles/4231426) guide. ### Custom field mapping Custom field mapping searches for the source value in the Unify response's own `custom_fields` list, a list of key/value pairs where the key is the custom field's `id` and the value is its value, rather than in the integration's raw response. Apideck already maps every Hubspot custom field into the `custom_fields` property on the Unify response, as shown below. Because each consumer configures their own custom fields in their own Hubspot account, those `id` values are unique per consumer. _Unify response with mapped `custom_fields`:_ ```json { "status_code": 200, "status": "OK", "service": "hubspot", "resource": "contacts", "operation": "one", "data": { "id": "551", "name": "Emilia Earhart", "first_name": "Emilia", "last_name": "Earhart", "title": "Pilot", "custom_fields": [ { "id": "assigned_csm", "value": "Kristof W." }, { "id": "t_shirt_size", "value": "Small" } ], "updated_at": "2024-01-12T10:42:21.467Z", "created_at": "2020-10-02T14:48:17.728Z" } } ``` By defining a new field "T-shirt Size" you are extending the Unify model. ![Custom Field mapping - Add a new field to Unify](/guides/field-mapping/admin-custom-mapping-overview.png) It will allow you to ask the consumer to configure the mapping for the correct custom field for their "T-shirt Size" field in Vault. ![Custom Field mapping - Map custom field in Vault](/guides/field-mapping/vault-custom-field.png) This will result in the value of the "T-shirt Size" custom field that will be included in the Unify response. _Unify response with `custom_mappings` property, containing the field mapping for "T-shirt Size"._ ```json { "status_code": 200, "status": "OK", "service": "hubspot", "resource": "contacts", "operation": "one", "data": { "id": "551", "name": "Emilia Earhart", "first_name": "Emilia", "last_name": "Earhart", "title": "Pilot", "custom_fields": [ { "id": "assigned_csm", "value": "Kristof W." }, { "id": "t_shirt_size", "value": "Small" } ], "updated_at": "2024-01-12T10:42:21.467Z", "created_at": "2020-10-02T14:48:17.728Z", "custom_mappings": { "lifecycle_stage": "lead", "tshirt_size": "Small" } } } ``` You can repeat the mapping process for all integrations, resulting in having the "T-shirt Size" field available in the Unify response for all integrations. For more details on how to configure a Custom field mappings, check out the [Custom Mapping](https://help.apideck.com/en/articles/4231554) guide.