Configuring Data Warehouse and Dashboards binding settings in Management API

Configuring Data Warehouse and Dashboards binding settings in Management API#

This guide explains how to manage destination binding settings using the Management API for two distinct destination types:

  • Data Warehouse (also called Adverity Data Storage, or ADS) is the current Adverity-managed or external warehouse destination. It can also route data into Dashboards workspaces as part of the same binding. For the equivalent user interface flow, see Loading data into Data Warehouse.

  • Dashboards is a separate, legacy destination for customers who see separate Explore and Present links in the platform navigation menu and do not use an internal warehouse. This destination type is being phased out in favor of Data Warehouse. For the equivalent user interface flow, see Loading data into Dashboards.

Note

If you are unsure which destination type applies to your Adverity instance, check the notes at the top of the two user interface guides linked above, or send a GET request to https://{{INSTANCE}}/api/target-types/ and look for either a Data Warehouse or a Dashboards entry.

Prerequisites#

Before you complete the procedures in this guide, perform all of the following actions:

  • Obtain a Management API key with the appropriate scope:

    • destination:read to list and view bindings.

    • destination:write to create, update, or delete bindings.

    For more information, see Authorizing to Management API.

  • Determine the following IDs:

    • TARGET_TYPE_ID — the content-type ID of the destination. To find it, send a GET request to https://{{INSTANCE}}/api/target-types/ and look for the entry named Data Warehouse or Dashboards, depending on which destination type you use.

    • TARGET_ID — the numeric ID of the destination instance. After obtaining the TARGET_TYPE_ID, send a GET request to https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/ and locate the relevant ID.

Configuring Data Warehouse binding settings#

Data Warehouse limitations#

The Management API does not provide endpoints to enumerate the valid values for workspace_single_mapping and workspace_mapping_table. To obtain the IDs of valid workspaces and mapping tables, use the Adverity user interface.

Listing Data Warehouse bindings#

To list the Data Warehouse bindings, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you obtain the list of Data Warehouse bindings, including the current values of all configurable settings.

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/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Retrieving a single Data Warehouse binding#

To retrieve the settings of a specific Data Warehouse binding, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you obtain the current settings for the specified binding.

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/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Discovering available Data Warehouse settings#

To see all configurable fields, their accepted values, and help text before creating or updating a binding, send an OPTIONS request.

To discover available settings, follow these steps:

  1. Create an OPTIONS request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, the response contains the full schema for the binding endpoint, including all accepted fields, their types, choices, and which are required.

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

curl --location --request OPTIONS 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Creating a Data Warehouse binding#

To create a new Data Warehouse binding, follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include the binding parameters. At minimum, include the datastream field. For the full list of available parameters, see Available Data Warehouse binding settings:

    {
    "datastream": "{{DATASTREAM_ID}}",
    "ingestion_mode": 1,
    "workspace_mapping_type": 1,
    "workspace_single_mapping": "{{WORKSPACE_ID}}",
    "datasource_label": "My Datasource"
}

  5. Send the request.

As a result, you created a new Data Warehouse binding. The response contains the created binding with all its settings and returns HTTP 201.

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

curl --location --request POST 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"datastream": "{{DATASTREAM_ID}}", "ingestion_mode": 1, "workspace_mapping_type": 1, "workspace_single_mapping": "{{WORKSPACE_ID}}", "datasource_label": "My Datasource"}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Note

The target field is taken from the URL path and is read-only. Any target value included in the request body is ignored. Creating a second binding for the same datastream and destination pair returns a 400 response.

Updating Data Warehouse binding settings#

To update the settings of an existing Data Warehouse binding, follow these steps:

  1. Create a PATCH request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include only the settings you want to update:

    {
    "datasource_label": "Updated Label",
    "overwrite_key_columns": true
}

  5. Send the request.

As a result, the binding is updated and the response reflects the new values.

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

curl --location --request PATCH 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"datasource_label": "Updated Label", "overwrite_key_columns": true}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Note

Extra or unknown fields in the request body are ignored — only the fields listed in Available Data Warehouse binding settings are applied.

Deleting a Data Warehouse binding#

To delete an existing Data Warehouse binding, follow these steps:

  1. Create a DELETE request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you deleted the Data Warehouse binding and the destination is removed from the datastream. The response returns HTTP 204 with no body.

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

curl --location --request DELETE 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Available Data Warehouse binding settings#

The settings are grouped into three categories: ingestion settings, Dashboards workspace selection, and other settings. To see the full set of accepted values for each field, send an OPTIONS request as described in Discovering available Data Warehouse settings.

Ingestion settings#

These settings correspond to the data loading options described in Understanding warehouse data storage options.

Parameter

Description

ingestion_mode

Controls how new data is loaded into the connected warehouse — for example, overwriting specific days, appending all new rows, or overwriting all rows. Use the OPTIONS endpoint to see all accepted values.

row_date_column_name

The name of the date column used to determine which data is overwritten. Required when ingestion_mode overwrites data by date.

overwrite_key_columns

Boolean. When true, existing rows are overwritten based on key columns configured in the Data Mapping for this datastream.

Routing data to Dashboards workspaces#

These settings correspond to the Dashboards section described in Loading data into Data Warehouse, and control whether and how data loaded into Data Warehouse is also made available in Dashboards.

Parameter

Description

workspace_mapping_type

Controls how the datastream’s data is mapped to a Dashboards workspace. Use the OPTIONS endpoint to see all accepted values.

workspace_single_mapping

The numeric ID of the Dashboards workspace to map to. Required when workspace_mapping_type is set to single-workspace mapping. Only client-type workspaces are valid. See Data Warehouse limitations for how to obtain valid IDs.

workspace_mapping_column_name

The name of the column in your data extract used to map data to Dashboards workspaces. Required when workspace_mapping_type is set to column-based mapping.

workspace_mapping_table

The workspace mapping table that resolves column values to Dashboards workspaces. Required when workspace_mapping_type is set to column-based mapping. See Data Warehouse limitations for how to obtain valid IDs.

workspace_missing_action

The action to take when a Dashboards workspace cannot be resolved from the mapping column. Use the OPTIONS endpoint to see available choices.

Other Data Warehouse settings#

Parameter

Description

datasource_label

A label for the data source. Must be title-case. Appears as the data source name in Dashboards, if the binding is also mapped to a Dashboards workspace.

enabled

Boolean. When true, the binding is active and data is loaded on each fetch.

Read-only fields#

Note

Unlike the equivalent fields in the Dashboards (legacy) binding type, overwrite_datastream, overwrite_filename, and overwrite_date_range_column_name are read-only for Data Warehouse bindings. They are computed from the ingestion_mode setting described in Ingestion settings rather than set directly.

Field

Description

id

The numeric ID of the binding.

target

The numeric ID of the Data Warehouse destination. Read-only; set from the URL path.

datastream

The numeric ID of the bound datastream.

overwrite_datastream

Boolean. Read-only. Whether existing data for the datastream is overwritten on each load.

overwrite_filename

Boolean. Read-only. Whether existing data with the same data extract filename is overwritten.

overwrite_date_range_column_name

Read-only. The name of the date column used to determine which data is overwritten, if configured through the Adverity user interface.

Configuring Dashboards binding settings (legacy)#

Note

Dashboards is a legacy destination, being phased out in favor of Data Warehouse. Use this section only if the destination type you use is named Dashboards in GET /api/target-types/ — this is typically the case if you see separate Explore and Present links in the platform navigation menu, without an internal warehouse. For more information, see Loading data into Dashboards.

Dashboards limitations#

The Management API does not provide endpoints to enumerate the valid values for workspace_single_mapping and workspace_mapping_table. To obtain the IDs of valid workspaces and mapping tables, use the Adverity user interface.

Listing Dashboards bindings#

To list the Dashboards bindings, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you obtain the list of Dashboards bindings, including the current values of all configurable settings.

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/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Retrieving a single Dashboards binding#

To retrieve the settings of a specific Dashboards binding, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you obtain the current settings for the specified binding.

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/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Discovering available Dashboards settings#

To see all configurable fields, their accepted values, and help text before creating or updating a binding, send an OPTIONS request.

To discover available settings, follow these steps:

  1. Create an OPTIONS request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, the response contains the full schema for the binding endpoint, including all accepted fields, their types, choices, and which are required.

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

curl --location --request OPTIONS 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Creating a Dashboards binding#

To create a new Dashboards binding, follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include the binding parameters. At minimum, include the datastream field. For the full list of available parameters, see Available Dashboards binding settings:

    {
    "datastream": "{{DATASTREAM_ID}}",
    "workspace_mapping_type": 1,
    "workspace_single_mapping": "{{WORKSPACE_ID}}",
    "datasource_label": "My Datasource"
}

  5. Send the request.

As a result, you created a new Dashboards binding. The response contains the created binding with all its settings and returns HTTP 201.

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

curl --location --request POST 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"datastream": "{{DATASTREAM_ID}}", "workspace_mapping_type": 1, "workspace_single_mapping": "{{WORKSPACE_ID}}", "datasource_label": "My Datasource"}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Note

The target field is taken from the URL path and is read-only. Any target value included in the request body is ignored. Creating a second binding for the same datastream and destination pair returns a 400 response.

Updating Dashboards binding settings#

To update the settings of an existing Dashboards binding, follow these steps:

  1. Create a PATCH request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. In the HTTP request header, include the parameter Content-Type with value application/json.

  4. In the HTTP request body, include only the settings you want to update:

    {
    "datasource_label": "Updated Label",
    "overwrite_filename": true
}

  5. Send the request.

As a result, the binding is updated and the response reflects the new values.

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

curl --location --request PATCH 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{"datasource_label": "Updated Label", "overwrite_filename": true}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Note

Extra or unknown fields in the request body are ignored — only the fields listed in Available Dashboards binding settings are applied.

Deleting a Dashboards binding#

To delete an existing Dashboards binding, follow these steps:

  1. Create a DELETE request to the following endpoint:

    https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

As a result, you deleted the Dashboards binding and the destination is removed from the datastream. The response returns HTTP 204 with no body.

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

curl --location --request DELETE 'https://{{INSTANCE}}/api/target-types/{{TARGET_TYPE_ID}}/targets/{{TARGET_ID}}/mappings/{{BINDING_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Available Dashboards binding settings#

The settings are grouped into three categories: Dashboards workspace selection, overwrite settings, and other settings. To see the full set of accepted values for each field, send an OPTIONS request as described in Discovering available Dashboards settings.

Dashboards workspace selection#

Parameter

Description

workspace_mapping_type

Controls how the datastream’s data is mapped to a workspace. Known values: 1 (single workspace mapping), 2 (column-based mapping). Use the OPTIONS endpoint to see all accepted values.

workspace_single_mapping

The numeric ID of the Dashboards workspace to map to. Required when workspace_mapping_type is 1. Only client-type workspaces are valid. See Dashboards limitations for how to obtain valid IDs.

workspace_mapping_column_name

The name of the column in your data extract used to map data to workspaces. Required when workspace_mapping_type is 2.

workspace_mapping_table

The workspace mapping table that resolves column values to workspaces. Required when workspace_mapping_type is 2. See Dashboards limitations for how to obtain valid IDs.

workspace_missing_action

The action to take when a workspace cannot be resolved from the mapping column. Use the OPTIONS endpoint to see available choices.

Dashboards overwrite settings#

Parameter

Description

overwrite_key_columns

Boolean. When true, existing rows are overwritten based on key columns configured in the Data Mapping for this datastream.

overwrite_datastream

Boolean. When true, existing data for the datastream is overwritten on each load.

overwrite_filename

Boolean. When true, existing data with the same data extract filename is overwritten.

overwrite_date_range_column_name

The name of the date column used to determine which data is overwritten. When set, previously loaded data within the matching date range is replaced.

Other Dashboards settings#

Parameter

Description

datasource_label

A label for the data source. Must be title-case. Appears as the data source name in Dashboards.

is_insights_mediaplan

Boolean. When true, the binding is treated as a media plan binding in Dashboards.

enabled

Boolean. When true, the binding is active and data is loaded on each fetch.

Read-only base fields#

Field

Description

id

The numeric ID of the binding.

target

The numeric ID of the Dashboards destination. Read-only; set from the URL path.

datastream

The numeric ID of the bound datastream.
Contents