API - JSON Transformer

By default, API integrations parse only top-level attributes of incoming JSON records. This poses a problem when the current state of your outbound data isn't structured as a list of flat objects. The JSON Transformer allows you to surface nested data, making it available for mapping to Ambition fields.

Configuring a JSON Transformer

There are several options available when configuring a JSON transformer.

Schema Builder

You can click "View Schema Builder" at any time to review the fields that your configuration surfaces for mapping to Ambition. To review the configuration, you must first choose a file that you've uploaded to the integration. Once you choose an upload, you'll see the current configuration applied to the file you've chosen, allowing you to select exposed fields and add them directly to the Field Mappings.

JSON Mapping

In order to surface fields from nested objects, you need to identify the objects that contain them. A source object is a link to a list of objects in your JSON file which contain the fields you wish to surface.

Example

Adding "body.records" as a source object for the above file will surface the fields "email", "date", and "meetings_set" for mapping to Ambition configuration.

You can add multiple source objects, but objects in sources are related to each other by their order, alone. Be sure that if you're adding multiple sources, the field objects are ordered consistently across all sources. In the example below, if you add sources "body.records" and "body.extended_attributes", the resulting values for the user on 2023-06-12 would include a "meetings_set" value of 3 and "call_duration" value of 120.

Example

Flattening and Destination Objects

When you have more than one source object mapped, you may find that field names conflict. In the example below, you can see that the values for the two metrics are nested inside metric source objects, in otherwise generic fields named "value". In order to map both of these values, you could add a destination object for each source object and flatten the file with dot notation in order to reference the field names in mappings.