# Adform Export Integration

The integration exports two kinds of files. A **taxonomy** export creates the audience definitions in Adform DMP, and an **audience** export adds users to those audiences or removes them. Audiences must exist in Adform DMP before you export user data into them, so a new setup always starts with a taxonomy export.

## What You Can Do With This Integration

- Create audiences in Adform DMP by exporting a taxonomy file that defines each audience, its category, and its time-to-live.
- Add users to one or more existing audiences, identified by hashed email, mobile advertising ID, cookie ID, or your own CRM ID.
- Remove a user from a specific audience, or from all audiences at once — for example, to honor a GDPR erasure request.


## How the Integration Delivers Data

The Adform Export Integration does not call an Adform API. It generates a file per export job and uploads it to an Amazon S3 bucket that Adform owns and scans:

1. You configure the integration with your Adform DMP Account ID, the target, the ID type, and the operation.
2. Treasure AI validates the DMP Account ID against the list of Adform DMP accounts registered for your Treasure AI account.
3. The integration generates the file from your query or segment results — comma-separated CSV for taxonomy, TAB-separated and GZip-compressed for audience data.
4. The integration uploads the file to the Adform S3 bucket under a path derived from your DMP Account ID, the ID type, and the export date.
5. Adform scans the bucket every 15 minutes. A newly detected file is read and applied, and the audience is typically populated within one to two hours.


Because delivery is file-based, a successful Treasure AI job means the file was accepted by S3, not that Adform has finished processing it. Confirm audience membership in Adform DMP.

### S3 Paths

The integration constructs the destination path — you do not configure it.

| Target  | Path  |
|  --- | --- |
| Taxonomy | `data-providers/treasure-data/dt=YYYYMMDD/taxonomy/{dmp_account_id}/{file_name}.csv` |
| Audience | `data-providers/treasure-data/dt=YYYYMMDD/{hashed_email|maid|cookie|first_party}/{file_name}.gz` |


## Prerequisites

- Basic knowledge of Treasure AI.
- An active Adform DMP account.
- Your Adform DMP Account ID, and the Owner ID of each audience you export into. Both come from Adform.
- Your Adform DMP Account ID registered with Treasure AI. Registration happens during onboarding — contact your Customer Success representative or technical support to add a DMP Account ID. Exports using an unregistered ID fail with `DMP Account ID not authorized for this account`.
- For the `cookie` ID type, the Adform User ID Sync pixel deployed on your website. Pixel deployment is outside the scope of this integration.


## Requirements and Limitations

- Audiences must exist in Adform DMP before you export user data into them. Run a taxonomy export first, and confirm in Adform DMP that the audiences were created.
- Query columns must use the exact column names in this page. Names are matched case-insensitively and surrounding spaces are ignored, but two columns whose names differ only by case fail the job.
- Column values must not contain a comma, a TAB, a double quote, or a line break. The output formats are positional and nothing is escaped, so such a value would corrupt the record.
- Owner ID values accept only the characters `a-z`, `A-Z`, `0-9`, `.`, `_`, and `-`.
- Files are split automatically at 100 MB of compressed output. Adform's hard limit is 4 GB per file.
- Adform keeps uploaded files for 14 days, and at most 900 files. Uploading more often than Adform can consume is the main cause of hitting the file limit.
- Adform disables the bucket after two weeks without an upload. Schedule your exports frequently enough to keep the bucket active.
- GZip compression, the TAB separator, and the absence of a header row are fixed for audience files. These are Adform requirements and are not configurable.


## Create a New Connection

In Treasure Console, create and configure the data connection before running your query. This integration has no OAuth or credential step: Treasure AI holds the S3 credentials internally, and the only value you supply is your Adform DMP Account ID.

1. Open **Treasure Console**.
2. Navigate to **Integrations Hub > Catalog**.
3. Search for and select **Adform Export**.


![](/assets/new_authen.bb05088df93ea7d7d77e9043e9c01ccd7ffae589b2a84cb4532d9d299aaaefb0.c42be0a5.webp)

1. Select **Create Authentication**, and enter your Adform DMP Account ID.
2. Select **Continue**, enter a name for the authentication, and select **Done**.


![](/assets/new_authen_config.72854cd2a0aeb6cf02c09a62dd82223f46ae3c1ff45e9339b9f8a26e0865907d.c42be0a5.webp)

### Authentication Fields

| Field Name  | Type  | Description  |
|  --- | --- | --- |
| **Adform DMP Account ID** (Required) | string | The Adform DMP account that receives the data. Must be one of the DMP Account IDs registered for your Treasure AI account. |


## Configure a Query Result for Export

Treasure Console supports multiple ways to export data. To export from the Data Workbench:

1. Navigate to **Data Workbench > Queries**.
2. Select **New Query**, and define your query as described in [Define Your Query](#define-your-query).
3. Select **Export Results**.
4. Select an existing authentication, or create a new one following the previous section.
5. Configure the parameters described in [Configuration Parameters](#configuration-parameters), and select **Done**.


![Taxonomy configuration](/assets/taxonomy.ac06e0ab5cead864e4979bd8941761adab7a8fddc1f91fbf5d112b4d18ca32b2.c42be0a5.webp)

![Audience configuration](/assets/audience.1213768aca362bb8ade1eb0a8683e8398c8b3a0a209a0f20a20ba36bd6bc0a28.c42be0a5.webp)

## Define Your Query

Your query must return the columns required by the target and the ID type you configured. Other columns are ignored. A required column that is null or empty makes the record invalid: the record is skipped when **Skip Invalid Records** is enabled, and the job fails otherwise.

### Audience Columns

An audience export needs one ID column and at least one Owner ID column.

| Column  | Required  | Data Type  | Description  |
|  --- | --- | --- | --- |
| `email` / `maid` / `cookie_id` / `crm_id` | Yes | string | The user identifier. Which column is required depends on the ID type — see the next table. |
| `owner_id` | Yes | string | The Adform Owner ID of the audience the user belongs to. Required for the `remove` operation, and required for `add` unless you supply numbered columns instead. |
| `owner_id1`, `owner_id2`, … `owner_idN` | No | string | Additional audiences for the same user. Accepted by the `add` operation only. |


### ID Column per ID Type

| ID Type  | Required Column  | Format and Validation  | Example Value  |
|  --- | --- | --- | --- |
| `hashed_email` | `email` | A 64-character lowercase hex SHA-256 hash is used as-is. Any other value is treated as a raw email address, trimmed, and hashed with SHA-256 by the integration. The value is not lowercased before hashing. | `taro.yamada@example.com` or `b6ebd83922edfa96b0ff9166a958badcc230dd68d2315ddfea22f20eaf05994a` |
| `maid` | `maid` | Non-empty string. The mobile advertising ID (IDFA or AAID). | `550e8400-e29b-41d4-a716-446655440000` |
| `cookie` | `cookie_id` | Non-empty string. A Treasure AI generated cookie ID: `td_client_id`, `td_ssc_id`, or `td_global_id`. | `951741598523654` |
| `first_party` | `crm_id` | Non-empty string. Your own CRM identifier. | `USR-00012345` |


Because a raw email address is hashed automatically, you do not need to hash it in your query. If you hash it yourself, it is sent as-is.

### Adding Users to Audiences

With **Operation** set to `add`, every non-empty Owner ID column contributes an audience for that user. Values repeated across columns are sent once, in the order the columns appear. A record whose Owner ID columns are all empty is invalid.

Example query output:

| email  | owner_id  | owner_id1  | owner_id2  |
|  --- | --- | --- | --- |
| taro.yamada@example.com | 14471 | 14445 | 14448 |
| hanako.suzuki@example.com | 14485 |  |  |


### Removing Users From Audiences

With **Operation** set to `remove`, the query must return a single `owner_id` column. Numbered `owner_id1` … `owner_idN` columns are rejected, because each record removes the user from either one audience or all of them.

| `owner_id` Value  | Generated Value  | Meaning  |
|  --- | --- | --- |
| A numeric Owner ID, for example `14471` | `sg=--14471` | Remove the user from that audience. |
| `all` | `--DeleteAll` | Remove the user from every audience in the DMP account. |


Example query output:

| email  | owner_id  |
|  --- | --- |
| taro.yamada@example.com | 14471 |
| ken.tanaka@example.com | all |


### Taxonomy Columns

A taxonomy export defines the audiences themselves. `ref_id` carries the Owner ID that audience data later refers to, so keep the values you use here — they are the `owner_id` values of your audience exports.

| Column  | Required  | Data Type  | Default  | Validation  | Description  |
|  --- | --- | --- | --- | --- | --- |
| `ref_id` | Yes | string | — | Non-empty. Allowed characters: `a-z`, `A-Z`, `0-9`, `.`, `_`, `-` | The Owner ID of the audience. |
| `name` | Yes | string | — | Non-empty | The audience name shown in Adform DMP. |
| `category` | Yes | string | — | Non-empty | The parent category path, with levels separated by `/`, for example `Demography/Gender`. Adform creates the category if it does not exist. |
| `ttl` | No | long | `21` | Positive integer | Time to live, in days. |
| `frequency` | No | long | `1` | Positive integer | The frequency setting of the audience. |
| `fee` | No | long or double | `0` | Zero or greater | The price of the audience. |
| `status` | No | string | `Active` | `Active` or `Inactive` | Whether the audience is active. Matched case-insensitively. |
| `data_type` | No | long | `1` | `1`, `2`, or `3` | `1` for first-party data you collected yourself, `2` for second-party data shared with direct partners, `3` for third-party data you sell as a branded data provider. |
| `iab_taxonomy_id` | No | string | — | — | IAB taxonomy category IDs to assign to the audience, separated by semicolons, for example `1;15;16`. |


An optional column that is missing or empty takes its default. The five defaults above mean a minimal taxonomy query returns only `ref_id`, `name`, and `category`.

Example query output:

| ref_id | name | category | ttl | frequency | fee | status | data_type | iab_taxonomy_id |
|  --- | --- | --- | --- | --- | --- | --- | --- | --- |
| G1-01 | Male | Demography/Gender | 21 | 1 | 1 | Active | 1 | 1;15;16 |
| G1-02 | Female | Demography/Gender | 21 | 1 | 2 | Active | 2 | 1;15;17 |
| G12-01 | 18-24 | Demography/Age | 21 | 1 | 0.5 | Active | 3 | 1;2;4 |


## Configuration Parameters

| Parameter Name  | Type  | Default  | Description  |
|  --- | --- | --- | --- |
| **Target** (Optional) | string | `audience` | What the export creates. `taxonomy` defines audiences in Adform DMP, `audience` adds users to or removes users from existing audiences. |
| **ID Type** (Optional) | string | `hashed_email` | The identifier used to match users: `hashed_email`, `maid`, `cookie`, or `first_party`. Determines the required ID column and the S3 folder. Ignored when Target is `taxonomy`. |
| **Operation** (Optional) | string | `add` | `add` puts users into the audiences named by the Owner ID columns, `remove` takes them out. Ignored when Target is `taxonomy`. |
| **Skip Invalid Records** (Optional) | boolean | `true` | When enabled, invalid records are counted and skipped, and the first 100 error messages appear in the job log. When disabled, the first invalid record fails the job and nothing is uploaded. |


## Activate a Segment in Audience Studio

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to **Audience Studio**.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select **Create Activation.**
4. In the **Details** panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the **Output Mapping** panel.


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- Attribute Columns
  - Select **Export All Columns** to export all columns without making any changes.
  - Select **+ Add Columns** to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select **+ Add Columns**to add new columns for your activation output.
- String Builder
  - **+ Add string** to create strings for export. Select from the following values:
    - String: Choose any value; use text to create a custom value.
    - Timestamp: The date and time of the export.
    - Segment Id: The segment ID number.
    - Segment Name: The segment name.
    - Audience Id: The parent segment number.


1. Set a **Schedule**.


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- Select the values to define your schedule and optionally include email notifications.


1. Select **Create**.


If you need to create an activation for a batch journey, review [Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation).

### (Optional) Schedule Query Export Jobs

You can use Scheduled Jobs with Result Export to periodically write the output result to a target destination that you specify.

Treasure Data's scheduler feature supports periodic query execution to achieve high availability.

When two specifications provide conflicting schedule specifications, the specification requesting to execute more often is followed while the other schedule specification is ignored.

For example, if the cron schedule is `'0 0 1 * 1'`, then the 'day of month' specification and 'day of week' are discordant because the former specification requires it to run every first day of each month at midnight (00:00), while the latter specification requires it to run every Monday at midnight (00:00). The latter specification is followed.

#### Scheduling your Job Using Treasure Console

1. Navigate to **Data Workbench > Queries**
2. Create a new query or select an existing query.
3. Next to **Schedule**, select None.
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. In the drop-down, select one of the following schedule options:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| Drop-down Value | Description |
|  --- | --- |
| Custom cron... | Review [Custom cron... details](#custom-cron-details). |
| @daily (midnight) | Run once a day at midnight (00:00 am) in the specified time zone. |
| @hourly (:00) | Run every hour at 00 minutes. |
| None | No schedule. |


#### Custom cron... Details

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron Value** | **Description** |
|  --- | --- |
| `0 * * * *` | Run once an hour. |
| `0 0 * * *` | Run once a day at midnight. |
| `0 0 1 * *` | Run once a month at midnight on the morning of the first day of the month. |
| "" | Create a job that has no scheduled run time. |


```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)
```

The following named entries can be used:

- Day of Week: sun, mon, tue, wed, thu, fri, sat.
- Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.


A single space is required between each field. The values for each field can be composed of:

div
| Field Value  | Example  | Example Description  |
|  --- | --- | --- |
| A single value, within the limits displayed above for each field. |  |  |
| A wildcard `'*'` to indicate no restriction based on the field. | `'0 0 1 * *'` | Configures the schedule to run at midnight (00:00) on the first day of each month. |
| A range `'2-5'`, indicating the range of accepted values for the field. | `'0 0 1-10 * *'` | Configures the schedule to run at midnight (00:00) on the first 10 days of each month. |
| A list of comma-separated values `'2,3,4,5'`, indicating the list of accepted values for the field. | `'0 0 1,11,21 * *'` | Configures the schedule to run at midnight (00:00) every 1st, 11th, and 21st day of each month. |
| A periodicity indicator `'*/5'` to express how often based on the field's valid range of values a schedule is allowed to run. | `'30 */2 1 * *'` | Configures the schedule to run on the 1st of every month, every 2 hours starting at 00:30. `'0 0 */5 * *'` configures the schedule to run at midnight (00:00) every 5 days starting on the 5th of each month. |
| A comma-separated list of any of the above except the `'*'` wildcard is also supported `'2,*/5,8-10'`. | `'0 0 5,*/10,25 * *'` | Configures the schedule to run at midnight (00:00) every 5th, 10th, 20th, and 25th day of each month. |


1. (Optional) You can delay the start time of a query by enabling the Delay execution.


### Execute the Query

Save the query with a name and run, or just run the query. Upon successful completion of the query, the query result is automatically exported to the specified destination.

Scheduled jobs that continuously fail due to configuration errors may be disabled on the system side after several notifications.

(Optional) You can delay the start time of a query by enabling the Delay execution.

## (Optional) Export Integration Using Treasure Workflow

within Treasure Workflow. Learn more at [Exporting Data with Parameters](/products/customer-data-platform/data-workbench/workflows/exporting-data-with-parameters)

Create the audiences with a taxonomy export:

```yaml
_export:
  td:
    database: adform_db

+adform_taxonomy_task:
  td>: taxonomy.sql
  database: ${td.database}
  result_connection: new_created_adform
  result_settings:
    type: adform
    dmp_account_id: "12345"
    target: taxonomy
```

Add users to those audiences:

```yaml
_export:
  td:
    database: adform_db

+adform_audience_add_task:
  td>: audience.sql
  database: ${td.database}
  result_connection: new_created_adform
  result_settings:
    type: adform
    dmp_account_id: "12345"
    target: audience
    id_type: hashed_email
    operation: add
```

Remove users from an audience, or from all audiences:

```yaml
_export:
  td:
    database: adform_db

+adform_audience_remove_task:
  td>: removal.sql
  database: ${td.database}
  result_connection: new_created_adform
  result_settings:
    type: adform
    dmp_account_id: "12345"
    target: audience
    id_type: hashed_email
    operation: remove
```

### Parameters

| Name  | Description  | Value  | Default  | Required  |
|  --- | --- | --- | --- | --- |
| `type` | Connector type | `adform` | N/A | Yes |
| `dmp_account_id` | Adform DMP Account ID that receives the data | N/A | N/A | Yes |
| `target` | What the export creates | `taxonomy`, `audience` | `audience` | No |
| `id_type` | Identifier used to match users | `hashed_email`, `maid`, `cookie`, `first_party` | `hashed_email` | No |
| `operation` | Whether users are added to or removed from audiences | `add`, `remove` | `add` | No |
| `skip_invalid_records` | Skip invalid records instead of failing the job | `true`, `false` | `true` | No |


## Troubleshooting

Configuration errors fail the job immediately. Record errors are skipped or fatal depending on **Skip Invalid Records**; when records are skipped, the job log reports the total number skipped and the first 100 messages.

| Message  | Cause  | Fix  |
|  --- | --- | --- |
| `DMP Account ID not authorized for this account` | The DMP Account ID is not registered for your Treasure AI account. | Check the ID for typos. If it is correct, contact your Customer Success representative to register it. |
| `dmp_account_id cannot be null or empty.` | The authentication has no DMP Account ID. | Edit the authentication and enter your Adform DMP Account ID. |
| `Schema invalid. Duplicate columns: …` | The query returns two columns whose names differ only by case or surrounding spaces. | Alias one of them in the query. |
| `Required column 'email' not found for ID type 'hashed_email'` | The query does not return the ID column that the configured ID type requires. | Add the column named in the message, or change the ID Type. |
| `Required column 'owner_id' not found` | An audience export returns no Owner ID column. | Add an `owner_id` column. |
| `Columns [owner_id1] are not accepted for the remove operation, only a single 'owner_id' column is allowed` | A remove export returns numbered Owner ID columns. | Return only `owner_id`, using one record per audience to remove. |
| `Column 'ref_id' must not be empty` | A required column is null, empty, or only spaces in that record. | Filter those rows out in the query, or supply a value. |
| `Column 'owner_id' value '…' contains unsupported symbols, allowed symbols are a-z, A-Z, 0-9, '.', '_', '-'` | An Owner ID contains an unsupported character. | Correct the value in the source data. |
| `Column 'ttl' must be of type long, but is 'string'` | A column has the wrong data type. | Cast the column in the query — see the data types in [Define Your Query](#define-your-query). |


If the job succeeds but the audience stays empty in Adform DMP, check the following, in order:

- The audience exists. Data for an audience that was never created by a taxonomy export is not activated.
- Fewer than two hours have passed. Adform scans the bucket every 15 minutes and populates audiences in one to two hours.
- The `owner_id` values match the `ref_id` values of your taxonomy export.
- The export has run in the last two weeks. Adform disables an inactive bucket, and uploads to a disabled bucket do not reach the DMP.


## See Also

- You can use a [Scheduled Job](/products/customer-data-platform/job-management/scheduling-jobs-using-td-console) with Result Export to periodically upload data to Adform.