All endpoints must be associated with a data schema - a formal description which defines the structure of associated data. The required schema for your third-party application should be available in the associated API documentation.
When you add a schema, you can also choose to apply field tags and set which (if any) fields are tracked.
To apply a schema for an endpoint, follow the steps below:
Step 1 Click the edit schema button:
Step 2 Paste in the required schema and save changes:
If you can't find a schema in your API documentation, you can run the API request in Postman, and then copy/paste the response as the schema.
Use the data path field to define the hierarchical level to be used for field tags and filters:
This is particularly important for JSON payloads, where the data structure is nested. Let's take an example below:
Here, all of our data is nested within one, top-level customers array object. If you scan down this example, you'll notice that there are two customer objects, each starting with an id for a customer record:
Now let's look at the data path field at the bottom of this page:
If we leave this set to empty, any subsequent field tags, mappings and filters will work on the basis that the top-level array object is our target. What we'd be saying in this scenario is 'don't treat the nested objects as separate records'.
So, for example, if we went on to apply a filter to match on first_name contains bob, we'd find a match in the second customer object but ALL objects would be returned because we're targeting the top-level array object. This isn't what we want.
What we actually want is to treat each of the lower-level customer objects as separate records. To do this, we navigate the data path and select the parent object - in this case, its customers:
When you save your new data path, you won't see any changes to the schema - but the change will be applied in the field tagging tab. Here, the schema preview shows the structure that applies as per your selected data path in the schema tab.
When you come to use instances of this connector in process flows and apply a filter shape, you'll see confirmation of the selected data path in filter settings - for example:
