Once you've created a custom unified field, you need to define the "mapping" for each of the integration you want this field to be enabled and usable for.

Adding an integration field mapping is done via the integration-level mapping tab after selecting a specific custom unified field.

ℹ️ Only integrations configured and enabled on the integrations page can be mapped.

Configuring the mapping

Although it's possible to map without using an underlying linked account, it's always advised to use a connected linked account (eg. a sandbox account) to have the most realistic view of what type of properties and fields may be available on the underlying integration.

Preview & Test

1. Preview Fields: (optional)
   • Select a source from the dropdown list to pull a sample set of field data.
   • Click on "Request" to preview the data.
   • Example preview JSON response:
     JSON

     {
       "employees": [
         {
           "id": "5",
           "firstName": "Anna",
           "lastName": "Skywalker",
           "terminationDate": "2024-05-28"
         }
       ]
     }
     

2. Field Mapping Steps:
   • Step 1: Select the source field you want to map from the integration.
   • Step 2: Enter the target custom field name.
   • Step 3: Use JSON path syntax to point to the relevant integration field
     • Example: $.employees.terminationDate

---

Tips & Tricks

Mapping array values

Some origin data will return a list of resources instead of a single resource (eg: all the documents instead of a specific document). In this case, you should make sure to use one of the provided default variables (eg: id) to find the element in the array that matches the ID.

JSON Path Syntax

Here's some of the json path synthax you can use:

• Basic Syntax:
  • $.model.field: Access a field at the root level.
  • $.model.field.subfield: Access a nested field.
• Array Handling:
  • $.[index]: Access a specific element in an array.
  • Example: $.employees.roles[0].title accesses the first employee's first name.
• Wildcard:
  • $.*: Access all fields at the current level.
  • Example: $.employees[*].firstName accesses the first name of all employees.

---

Additional Features:

• Typecasting: Values will be automatically typecasted to the defined variable type when possible (eg: if the variable type is a string but the underlying integration returns a number the number will be return as a string and vice-versa).

• Viewing Mappings: : once an integration mapping is configured, the source will be visible directly in the integration-level mapping list:

  

---

Using a Custom Unified Field

Once you have configured an integration custom field mapping you will need to make sure the field is enabled:

You can retrieving the data via any GET or LIST API request for the model you created the field on:

The unified custom field will be embedded in an property called unified_custom_fields.

ℹ️ When using SDKs (ie: Typescript SDK) the property may be camel cased instead (ie: unifiedCustomFields). The SDK will not have types for the individual properties contained in this object given it is fully customizable.