Retrieving connector field hierarchies in Management API

Retrieving connector field hierarchies in Management API#

This guide explains how to retrieve connector field dependency hierarchies with the Management API.

Introduction#

What is the field hierarchy?: The field hierarchy describes how a connector’s configuration fields depend on one another — which fields are linked and which field’s value determines the options available in another. For example, selecting an account can determine which campaigns are available.
Why retrieve it through the Management API?: Retrieving the field hierarchy programmatically helps you build integrations that configure datastreams correctly, because you can determine which fields depend on others before you set their values.

Prerequisites#

Before you complete the procedures in this guide, obtain a Bearer API key with the datastream:read scope. For more information, see Authorizing to Management API.

Limitations#

Both endpoints are read-only. They return the static field hierarchy extracted from the connector definitions and cannot be used to modify a configuration. The data changes only with connector releases.
Only connectors that have configuration fields with dependencies are included in the response.
These are v1 endpoints. They only support API keys generated in the Adverity user interface, which use the Bearer scheme in the Authorization header. For more information, see Generating an API key in Adverity.

Listing field hierarchies for all connectors#

To retrieve the field hierarchy for every connector that has field dependencies, follow these steps:

Create a GET request to the following endpoint:

https://{{INSTANCE}}/api/v1/connectors/field-hierarchies/

In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.

As a result, you obtain a paginated list of connector field hierarchies in the response.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/connectors/field-hierarchies/' \
--header 'Authorization: Bearer {{KEY}}'

Retrieving the field hierarchy for a single connector#

To retrieve the field hierarchy for one connector, follow these steps:

Create a GET request to the following endpoint, replacing {{CONNECTOR}} with the connector’s identifier:
```
https://{{INSTANCE}}/api/v1/connectors/{{CONNECTOR}}/field-hierarchy/
```
In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.
Send the request.

As a result, you obtain the connector’s field dependency hierarchy in the response.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/connectors/{{CONNECTOR}}/field-hierarchy/' \
--header 'Authorization: Bearer {{KEY}}'

Note

The {{CONNECTOR}} identifier is the value returned in the connector field of the list endpoint above. It is either a content type identifier in the form app_label/model_name or, for no-code connectors, nocode/slug.

Response#

The response describes the connector’s field dependency hierarchy. It contains the following fields:

Field	Description
`connector`	The connector’s identifier.
`fields`	An object keyed by field ID. Each field maps to an object with a `depends_on` list naming the fields it depends on.

The response has the following structure:

{
    "connector": "app_label/model_name",
    "fields": {
        "field_id": {
            "depends_on": [
                "parent_field_id"
            ]
        }
    }
}