Skip to content
Last updated

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
Taxonomydata-providers/treasure-data/dt=YYYYMMDD/taxonomy/{dmp_account_id}/{file_name}.csv
Audiencedata-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.

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

Authentication Fields

Field Name Type Description
Adform DMP Account ID (Required)stringThe 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.
  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, and select Done.

Taxonomy configuration

Audience configuration

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_idYesstringThe user identifier. Which column is required depends on the ID type — see the next table.
owner_idYesstringThe 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_idNNostringAdditional 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_emailemailA 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
maidmaidNon-empty string. The mobile advertising ID (IDFA or AAID).550e8400-e29b-41d4-a716-446655440000
cookiecookie_idNon-empty string. A Treasure AI generated cookie ID: td_client_id, td_ssc_id, or td_global_id.951741598523654
first_partycrm_idNon-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.com144711444514448
hanako.suzuki@example.com14485

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 14471sg=--14471Remove the user from that audience.
all--DeleteAllRemove the user from every audience in the DMP account.

Example query output:

email owner_id
taro.yamada@example.com14471
ken.tanaka@example.comall

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_idYesstring—Non-empty. Allowed characters: a-z, A-Z, 0-9, ., _, -The Owner ID of the audience.
nameYesstring—Non-emptyThe audience name shown in Adform DMP.
categoryYesstring—Non-emptyThe parent category path, with levels separated by /, for example Demography/Gender. Adform creates the category if it does not exist.
ttlNolong21Positive integerTime to live, in days.
frequencyNolong1Positive integerThe frequency setting of the audience.
feeNolong or double0Zero or greaterThe price of the audience.
statusNostringActiveActive or InactiveWhether the audience is active. Matched case-insensitively.
data_typeNolong11, 2, or 31 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_idNostring——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_idnamecategoryttlfrequencyfeestatusdata_typeiab_taxonomy_id
G1-01MaleDemography/Gender2111Active11;15;16
G1-02FemaleDemography/Gender2112Active21;15;17
G12-0118-24Demography/Age2110.5Active31;2;4

Configuration Parameters

Parameter Name Type Default Description
Target (Optional)stringaudienceWhat the export creates. taxonomy defines audiences in Adform DMP, audience adds users to or removes users from existing audiences.
ID Type (Optional)stringhashed_emailThe 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)stringaddadd puts users into the audiences named by the Owner ID columns, remove takes them out. Ignored when Target is taxonomy.
Skip Invalid Records (Optional)booleantrueWhen 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.

  • 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 Columnsto 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.

  • 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.

(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.

  4. In the drop-down, select one of the following schedule options:

    Drop-down ValueDescription
    Custom cron...Review 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.
    NoneNo schedule.

Custom cron... Details

Cron ValueDescription
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:

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

Create the audiences with a taxonomy export:

_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:

_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:

_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
typeConnector typeadformN/AYes
dmp_account_idAdform DMP Account ID that receives the dataN/AN/AYes
targetWhat the export createstaxonomy, audienceaudienceNo
id_typeIdentifier used to match usershashed_email, maid, cookie, first_partyhashed_emailNo
operationWhether users are added to or removed from audiencesadd, removeaddNo
skip_invalid_recordsSkip invalid records instead of failing the jobtrue, falsetrueNo

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 accountThe 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 foundAn 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 allowedA remove export returns numbered Owner ID columns.Return only owner_id, using one record per audience to remove.
Column 'ref_id' must not be emptyA 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.

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 with Result Export to periodically upload data to Adform.