Retrieving connector field hierarchies in 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, perform the following action:

• Use a Connect API key with Datastream: Read-only (datastream:read). Without this permission, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

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 Creating a Connect 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:

1. Create a GET request to the following endpoint:

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

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

3. 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:

1. Create a GET request to the following endpoint, replacing {{CONNECTOR}} with the connector’s identifier:

   https://{{INSTANCE}}/api/v1/connectors/{{CONNECTOR}}/field-hierarchy/
   

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

3. 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}}'

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

What’s next?

• Creating datastreams in Management API

• Configuring datastreams in Management API