# Equativ Export Integration

The integration exports two kinds of files. A **taxonomy** export creates the segment definitions in Equativ, and a **profile** export sets, adds, or removes segment membership for individual users. A segment must exist in Equativ before profile data referencing it is sent, so a new setup always starts with a taxonomy export.

## What You Can Do With This Integration

- Define segments in Equativ.
- Add a user to segments, remove a user from specific segments, or replace all of a user's segments in a single record.
- Send membership for any identifier Equativ accepts.
- Route profile data to the US, EU, or APAC Equativ environment.


## How the Integration Delivers Data

The Equativ Export Integration does not call an Equativ API. It generates one file per export job and uploads it to a Google Cloud Storage bucket that Equativ owns and ingests:

1. You configure the integration with your Equativ Segment Provider ID, the export type, and — for profile exports — the region and the identifier type.
2. Treasure AI validates the Segment Provider ID against the list of Segment Provider IDs registered for your Treasure AI account.
3. The integration generates the file from your query or segment results — a pipe-separated CSV with a header row, in UTF-8.
4. The integration uploads the file to the Equativ bucket for your export type and region, under a path derived from your Segment Provider ID.
5. Equativ ingests the file from the bucket and applies it.


Because delivery is file-based and Equativ reports nothing back, a successful Treasure AI job means the file was accepted by the bucket, not that Equativ finished processing it. Confirm the result in Equativ.

## Prerequisites

- Basic knowledge of Treasure AI.
- An active Equativ account
- Your Equativ Segment Provider ID. It comes from Equativ.
- Your Segment Provider ID registered with Treasure AI. Registration happens during onboarding — contact your Customer Success representative or technical support to add a Segment Provider ID. Exports using an unregistered ID fail with `Segment Provider ID not authorized for this account`.


## Requirements and Limitations

- Segments must exist in Equativ before you export profile data into them. Run a taxonomy export first, and confirm in Equativ that the segments 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 or spacing fail the job.
- Column values must not contain a pipe (`|`), a comma (`,`), a double quote (`"`), or a line break. The output format is positional and nothing is escaped, so such a value would corrupt the record.
- A taxonomy update replaces the whole row. Re-exporting a segment without a field it previously had erases that field, so always export every field you want Equativ to keep.
- If a taxonomy file contains the same `segment_id` more than once, Equativ imports only the last occurrence. The integration does not remove duplicates.
- Deleting a segment requires Equativ. Set `is_active` to `0` to remove a segment from targeting.
- Production supports up to 10 GB per day per folder. Sandbox environments accept considerably less.
- Profile data must go to the region where the users are targeted. Users uploaded to the wrong region are not available for targeting, and Equativ reports no error.


## 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 storage credentials internally, and the only value you supply is your Equativ Segment Provider ID.

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


![](/assets/new_connector_logo.c399e24994fdf6177118e1471a6cea6e4a9099093866d8f57e3baf9bdb8aac7d.0168b08c.webp)

1. Select **Create Authentication**, and enter your Segment Provider ID.


![](/assets/new_connector_config.a5e71e95384fc66f55846dc08fb0fe48034418e6939c20c1d93a586ab786be9e.0168b08c.webp)

1. Select **Continue**, enter a name for the authentication, and select **Done**.


### Authentication Fields

| Field Name  | Type  | Description  |
|  --- | --- | --- |
| **JSON keyfile** (Required) | string | Service account keyfile content. |
| **Segment Provider ID** (Required) | string | The unique identifier Equativ provides for your account. Must be one of the Segment Provider 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.
3. Select **Export Results** to configure the data export.
4. Select an existing Equativ authentication, or create a new one following the previous section.
5. Configure the export parameters.
6. Select **Done**.


## Define Your Query

Your query must return the columns required by the export 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.

### Taxonomy Columns

A taxonomy export defines the segments themselves.

| Column  | Required  | Data Type  | Default  | Validation  | Description  |
|  --- | --- | --- | --- | --- | --- |
| `segment_id` | Yes | string | — | Non-empty, at most 200 characters | Your own segment identifier. |
| `parent_segment_id` | No | string | empty | At most 200 characters | The parent segment, which builds the hierarchy shown in Equativ. Empty means the segment is top level. |
| `name` | Yes | string | — | Non-empty, at most 200 characters | The segment name shown in Equativ. |
| `description` | No | string | empty | At most 255 characters | An optional segment description. |
| `price` | No | long or double | `0` | Zero or greater | The price of the segment. Use `0` for no price. |
| `is_selectable` | No | boolean or long | `1` | `0`, `1`, `true`, or `false` | `1` if the segment is targetable, `0` if it exists only to build the hierarchy. |
| `ttl` | No | long | `43200` | Positive integer | Lifetime of the user-to-segment association, **in minutes**. The default `43200` is 30 days. |
| `is_active` | No | boolean or long | `1` | `0`, `1`, `true`, or `false` | `1` if the segment is active, `0` to deactivate it and remove it from targeting. |


An optional column that is missing or empty takes its default, so a minimal taxonomy query returns only `segment_id` and `name`.

Example query output:

| segment_id | parent_segment_id | name | description | price | is_selectable | ttl | is_active |
|  --- | --- | --- | --- | --- | --- | --- | --- |
| 123 |  | Gender: Male |  | 0.50 | true | 24000 | true |
| LF-1001 |  | Sport Readers |  |  |  |  |  |


This produces the following file. The second row shows every optional column taking its default.

```
SegmentId|ParentSegmentId|Name|Description|Price|IsSelectable|TTL|IsActive
123||Gender: Male||0.50|1|24000|1
LF-1001||Sport Readers||0|1|43200|1
```

### Profile Columns

A profile export sets, adds, or removes segment membership for a user. One record is one user.

| Column  | Required  | Data Type  | Description  |
|  --- | --- | --- | --- |
| `user_id` | Yes | string | The user identifier. |
| `segment_to_set` | At least one of the three | string | Comma-separated segments that **replace** all of the user's current segments. |
| `segment_to_add` | At least one of the three | string | Comma-separated segments to **add**. The user's existing segments are unchanged. |
| `segment_to_remove` | At least one of the three | string | Comma-separated segments to **remove**. Only the listed segments are removed. |
| `profile_id_source` | No | string | The identity-graph origin of the identifier. Requires back-end activation by Equativ; it is ignored otherwise, and profiles still ingest. Must not contain a pipe, a double quote, or a line break. An empty value is treated as absent. |


A record must carry at least one segment value across all three families, and each segment value is limited to 200 characters.

#### Numbered Segment Columns

Each of the three segment families also accepts numbered columns, so you do not have to concatenate segments in your query:

| Family  | Accepted Column Names  |
|  --- | --- |
| Set | `segment_to_set`, `segment_to_set1`, `segment_to_set2`, … |
| Add | `segment_to_add`, `segment_to_add1`, `segment_to_add2`, … |
| Remove | `segment_to_remove`, `segment_to_remove1`, `segment_to_remove2`, … |


The values of one family are combined into a single comma-separated field, in column-name order. Numbering does not have to start at `1` and does not have to be contiguous. Null, empty, and whitespace-only values are skipped rather than sent as empty entries, values are trimmed, and a value repeated within one family is sent once. Deduplication is per family, so the same segment appearing in both `segment_to_add` and `segment_to_remove` is sent in both — resolve that in your query.

A family with no values is sent as an empty field, with the separators intact. A record whose three families are all empty is invalid.

Example query output:

| user_id  | segment_to_set  | segment_to_set1  | segment_to_add  | segment_to_add1  | segment_to_remove  |
|  --- | --- | --- | --- | --- | --- |
| glVQoCkEgJcWya7NrUYac | 123 |  |  |  |  |
| ll1iA1FJMNDYGUHZef_3WCIMpc9e |  |  | 123 | 456 |  |
| nwGPW6UZeX4Esgcrz2_TbU87L |  |  | 111 | 112 | 113 |
| FR:75001 | 789 | 101 |  |  |  |


This produces the following file:

```
UserID|SegmentToSet|SegmentToAdd|SegmentToRemove
glVQoCkEgJcWya7NrUYac|123||
ll1iA1FJMNDYGUHZef_3WCIMpc9e||123,456|
nwGPW6UZeX4Esgcrz2_TbU87L||111,112|113
FR:75001|789,101||
```

When `profile_id_source` is returned, a fifth field is appended to every record.

## Configuration Parameters

![](/assets/export_taxonomy.23b963afca6f344d1e87e4a2432754717f1365d0700469637ccb4f3affb05244.0168b08c.webp)
![](/assets/export_profile.a9b3ef6bc23b4b89c6905960dedcc645118664e5e38a69d0517e256ecb3b8fc6.0168b08c.webp)

The Equativ Export Integration takes four export parameters.

| Parameter Name  | Type  | Default  | Description  |
|  --- | --- | --- | --- |
| **Export Type** (Required) | string | `taxonomy` | What the export creates. `taxonomy` defines segments in Equativ, `profile` sets, adds, or removes segment membership for users. |
| **Profile Region** (Required for `profile`) | string | `us` | The Equativ region that receives the data: `us`, `eu`, or `apac`. Ignored when Export Type is `taxonomy`. |
| **Encrypted Alternative IDs** (Optional) | string | `none` | Set to `utiq.com` or `id5-sync.com` when `user_id` holds encrypted alternative IDs from that provider. Leave it `none` for all other identifiers. Ignored when Export Type is `taxonomy`. |
| **Skip Invalid Records** (Optional) | boolean | `true` | When enabled, invalid records are counted and skipped. When disabled, the first invalid record fails the job and nothing is uploaded. |


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

## 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) Export Integration Using Treasure Workflow

You can run this export within Treasure Workflow. Learn more at [Using Workflows to Export Data with the TD Toolbelt](/tools/cli-and-sdks/api#workflow-commands).

Create the segments with a taxonomy export:

```yaml
_export:
  td:
    database: equativ_db

+equativ_taxonomy_task:
  td>: taxonomy.sql
  database: ${td.database}
  result_connection: new_created_equativ
  result_settings:
    type: equativ
    json_keyfile:
      content: |
      {xxxxxxxx}
    segment_provider_id: "abc28132y484ry24givncdkmn"
    export_type: taxonomy
    skip_invalid_records: true
```

Send profile membership for segments:

```yaml
_export:
  td:
    database: equativ_db

+equativ_profile_task:
  td>: profile.sql
  database: ${td.database}
  result_connection: new_created_equativ
  result_settings:
    type: equativ
    json_keyfile:
      content: |
      {xxxxxxxx}
    segment_provider_id: "abc28132y484ry24givncdkmn"
    export_type: profile
    profile_region: eu
    skip_invalid_records: true
```

### Parameters

| Name  | Description  | Value  | Default  | Required  |
|  --- | --- | --- | --- | --- |
| `type` | Connector type | `equativ` | N/A | Yes |
| `json_keyfile` | Google service account JSON key provided by Equativ. Object with content property. Example
json_keyfile:
content: |
{xxxxxxxx} | N/A | N/A | Yes |
| `segment_provider_id` | Equativ Segment Provider ID that receives the data | N/A | N/A | Yes |
| `export_type` | What the export creates | `taxonomy`, `profile` | `taxonomy` | Yes |
| `profile_region` | Equativ region that receives profile data | `us`, `eu`, `apac` | `us` | Yes if export_type is profile |
| `eid_provider` | Provider of the encrypted alternative IDs in `user_id` | `none`, `utiq.com`, `id5-sync.com` | `none` | No |
| `skip_invalid_records` | Skip invalid records instead of failing the job | `true`, `false` | `true` | No |


Example query for a profile export:

```sql
SELECT
  user_id,
  segment_to_add,
  segment_to_add1
FROM (
  VALUES ('glVQoCkEgJcWya7NrUYac', '123', '456')
) tbl (user_id, segment_to_add, segment_to_add1)
```

## Troubleshooting

If the job succeeds but the data does not appear in Equativ, check the following, in order:

- The segments exist. Profile data referencing a segment that was never created by a taxonomy export is not targetable, and Equativ reports no error.
- The taxonomy rows are complete. Equativ discards a segment that is missing a mandatory field, silently.
- **Profile Region** matches the region where you target the users. Users uploaded to another region are not available.
- The segment IDs in your profile export match the `segment_id` values of your taxonomy export.
- Your daily volume is under 10 GB for the folder.


## Others

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