Configuring Data Mapping in Management API

Configuring Data Mapping in Management API#

This guide explains how to retrieve all tracked columns, retrieve details about specific columns, and assign target columns with the Management API.

Prerequisites#

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

Retrieving current Data Mapping#

Retrieving all tracked columns in an instance#

To retrieve all tracked columns, follow these steps:

Note

/api/columns/ requires an API key with the Datastream scope (Read-only to retrieve columns, Write to update them). A key without this scope receives a 403 error.

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/columns/

  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.

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

curl --location -g --request GET 'https://{{INSTANCE}}/api/columns/' \
--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 all tracked columns in a datastream#

To retrieve all tracked columns per datastream, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/

  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.

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

curl --location -g --request GET 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/' \
--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 details of a specific column#

To retrieve details of a specific column, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/columns/{{COLUMN_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.

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

curl --location -g --request GET 'https://{{INSTANCE}}/api/columns/{{COLUMN_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.

Assigning target columns#

To assign columns you retrieved from the datastream to target columns, search through available target columns, create a new target column, and then assign the column to the target column. Sections below document this process.

Retrieving all available target columns#

To retrieve all available target columns in your instance, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/target-columns/

  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.

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

curl --location -g --request GET 'https://{{INSTANCE}}/api/target-columns/' \
--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.

Searching through available target columns by name#

This section uses an example in which you search for the target column called day using the name parameter. To search through the available target columns using the name parameter, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/target-columns/?name=day

  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.

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

curl --location -g --request GET 'https://{{INSTANCE}}/api/target-columns/?name=day' \
--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 available options for target column configuration#

To retrieve all available options for a new target column, including the optional parameters, follow the steps below:

  1. Create an OPTIONS request to the following endpoint:

    https://{{INSTANCE}}/api/target-columns/

  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.

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

curl --location -g --request OPTIONS 'https://{{INSTANCE}}/api/target-columns/' \
--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 new target column#

If you could not find a target column matching the necessary configuration, create a new target column which you can later assign to a column retrieved from a datastream. To create a new target column, follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/target-columns/

  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 following required parameters:

    {
    "type": "String",
    "name": "{{TARGET_COLUMN_NAME}}",
    "usage": "dimension"
}

    These are the required parameters. The value of the usage parameter is either dimension or metric.

    Note

    For metrics, the measure parameter defaults to SUM if not specified.

  5. Send the request.

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

curl --location -g --request POST 'https://{{INSTANCE}}/api/target-columns/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "String",
    "name": "{{TARGET_COLUMN_NAME}}",
    "usage": "dimension"
}'

Note

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

Viewing a target column mapping#

To view the list of default schema mappings assigned to a target column, follow the steps below:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/target-columns/{{TARGET_COLUMN_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. Optionally, add query parameters to filter the results:

    Parameter

    Description

    is_key_column

    Filter by whether the mapped source column is a key column. Accepted values: true, false.

    source_column_name

    Filter by the exact name of the source column.

    source_content_type

    Filter by the numeric content type ID of the connector the mapping applies to.

  5. Send the request.

As a result, you obtain a paginated list of default schema mappings for the target column.

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

curl --location -g --request GET 'https://{{INSTANCE}}/api/target-columns/{{TARGET_COLUMN_ID}}/mappings/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json'

Note

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

Updating column mapping#

In this section, you assign a column to a target column, or in other words, you configure the Data Mapping.

To update column mapping, follow these steps:

  1. Create a PATCH request to the following endpoint:

    https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/{{COLUMN_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 the following required parameters:

    {
    "is_key_column":"false",
    "set_default": "false",
    "target_column": {"id": {{TARGET_COLUMN_ID}}}
}

  5. Send the request.

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

curl --location -g --request PATCH 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/{{COLUMN_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "is_key_column":"false",
    "set_default": "false",
    "target_column": {"id": {{TARGET_COLUMN_ID}}}
}'

Note

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

Bulk assigning column mappings#

Instead of mapping columns one by one, you can assign multiple source columns to target columns in a single request. This operation replaces all existing mappings for the datastream - any column not included in the request body will be left unmapped.

To bulk assign column mappings, follow these steps:

  1. Create a PUT request to the following endpoint:

    https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/map/

  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 a list of mapping objects. Each object must contain the following parameters:

    • schema_column - the name of the target column to assign to.

    • source_column - the name of the source column from the datastream to map.

    • is_key_column (optional) - a boolean that marks the source column as a key column. When included, the value is applied to the matched source column. When omitted, the column’s existing is_key_column value is preserved. Source columns not included in the request are also unaffected.

    [
    {
        "schema_column": "{{TARGET_COLUMN_NAME}}",
        "source_column": "{{SOURCE_COLUMN_NAME}}",
        "is_key_column": true
    },
    {
        "schema_column": "{{TARGET_COLUMN_NAME}}",
        "source_column": "{{SOURCE_COLUMN_NAME}}"
    }
]

    Note

    If any schema_column or source_column value in the list is not found, the entire request fails and no mappings are changed.

  5. Send the request.

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

curl --location -g --request PUT 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/map/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "schema_column": "{{TARGET_COLUMN_NAME}}",
        "source_column": "{{SOURCE_COLUMN_NAME}}",
        "is_key_column": true
    }
]'

Note

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

Warning

Sending an empty list [] to this endpoint clears all column mappings and automatically disables any destination bindings that require column mappings to be configured. To remove individual mappings without affecting others, use PATCH /api/datastreams/{{DATASTREAM_ID}}/columns/ instead.

Removing column mapping#

In this section, you remove a column’s mapping (unmap a column) using Management API.

To remove a column’s mapping (unmap a column), follow these steps:

  1. Create a PATCH request to the following endpoint:

    https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/{{COLUMN_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 an empty target_column object:

    {
    "target_column": {}
}

  5. Send the request.

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

curl --location -g --request PATCH 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/columns/{{COLUMN_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "target_column": {}
}'

Note

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

Managing default schema mappings#

A default schema mapping assigns a source column — identified by its name and connector content type — to a target column, independently of any single datastream. Once configured, matching source columns in datastreams of that connector type are mapped to the target column automatically.

Listing all default schema mappings#

To list default schema mappings across all target columns, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/default-schema-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. Optionally, add query parameters to filter the results:

    Parameter

    Description

    is_key_column

    Filter by whether the mapped source column is a key column. Accepted values: true, false.

    source_column_name

    Filter by the exact name of the source column.

    source_content_type

    Filter by the numeric content type ID of the connector the mapping applies to.

  4. Send the request.

As a result, you obtain a paginated list of default schema mappings.

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

curl --location -g --request GET 'https://{{INSTANCE}}/api/default-schema-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 default schema mapping#

To create a default schema mapping, follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/default-schema-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 following parameters:

    Parameter

    Required

    Description

    source_column_name

    Yes

    The exact name of the source column to map.

    source_content_type

    Yes

    The numeric content type ID of the connector this mapping applies to.

    target_column_id

    Yes

    The ID of the target column to map the source column to.

    is_key_column

    No

    Whether to mark the mapped source column as a key column. Defaults to false.

  5. Send the request.

As a result, the default schema mapping is created and returned 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 -g --request POST 'https://{{INSTANCE}}/api/default-schema-mappings/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "source_column_name": "{{SOURCE_COLUMN_NAME}}",
    "source_content_type": {{CONTENT_TYPE_ID}},
    "target_column_id": {{TARGET_COLUMN_ID}}
}'

Note

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

Note

You can also create a default schema mapping scoped to one target column by sending this request to /api/target-columns/{{TARGET_COLUMN_ID}}/mappings/ instead. The target_column_id in the request body must match the {{TARGET_COLUMN_ID}} in the URL.

Note

A 409 response means the mapping was not created — usually because a concurrent request already mapped the same source column and content type, or because the referenced target column or content type was deleted in the same window:

{
    "detail": "A default mapping for this source column and content type already exists."
}

Re-read the existing mappings for this content type before retrying.

Updating a default schema mapping#

To update a default schema mapping, follow these steps:

  1. Create a PATCH request to the following endpoint:

    https://{{INSTANCE}}/api/default-schema-mappings/{{MAPPING_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 any of the parameters documented in Creating a default schema mapping that you want to change.

  5. Send the request.

As a result, the default schema mapping is updated and returned 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 -g --request PATCH 'https://{{INSTANCE}}/api/default-schema-mappings/{{MAPPING_ID}}/' \
--header 'Authorization: Token {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "is_key_column": true
}'

Note

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

This endpoint returns the same 409 response described in Creating a default schema mapping if the update collides with another mapping.

Removing a default schema mapping#

To remove a default schema mapping, follow these steps:

  1. Create a DELETE request to the following endpoint:

    https://{{INSTANCE}}/api/default-schema-mappings/{{MAPPING_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, the default schema mapping is removed.

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

curl --location -g --request DELETE 'https://{{INSTANCE}}/api/default-schema-mappings/{{MAPPING_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.

Exporting and importing workspace schema#

You can export the schema of a workspace — including all target columns and their default mappings — using the following endpoint:

GET https://{{INSTANCE}}/api/stacks/{{WORKSPACE_SLUG}}/schema/

Note

This endpoint uses efficient batch queries and is suitable for use in automated integrations and CI/CD workflows, regardless of the number of target columns in the schema. The response shape is unchanged from previous versions.

The response contains a target_columns array with each column’s name, data type, and any configured default mappings. An example response for a workspace with no target columns is:

{"target_columns": []}

For the full request syntax and authentication requirements, refer to the interactive API documentation at https://{{INSTANCE}}/api/v1/docs/.

Contents