Unified ID 2.0 Workflow

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This guide provides technical instructions for data engineers to configure and operate the predefined UID2 workflow within the Treasure Data platform.

The primary goal is to take your first-party Personally Identifiable Information (PII), such as email addresses and phone numbers, and convert it into privacy-safe Unified ID 2.0 (UID2) identifiers for use in the advertising ecosystem.

What is UID2?

From The Trade Desk - UID2 Overview | Unified ID 2.0 UID2 is a framework that enables deterministic identity for advertising opportunities on the open Internet for many participants across the advertising ecosystem. The UID2 framework enables logged-in experiences from publisher websites, mobile apps, and Connected TV (CTV) apps to monetize through programmatic workflows. Built as an open-source, standalone solution with its unique namespace, the framework offers the user transparency and privacy controls designed to meet local market requirements.

Some of the business values from this integration are below.

• Use a privacy-conscious form of customer data in media-buying platforms.
• Manage frequency and suppress audiences across channels and devices.
• Support identity use cases where cookies don’t exist.
• Offer opt-out, with the goal of improving consumer privacy controls.

Prerequisites

• Basic knowledge of Treasure Data
• Authorized Treasure Data account access
• Basic knowledge of UID2
  • https://www.thetradedesk.com/us/about-us/industry-initiatives/unified-id-solution-2-0
  • https://unifiedid.com/docs/intro or if you are in the EU: https://euid.eu/docs/intro
    • Please refer to the About EUID section

Terminology

Request to Access UID2.0

Before setting up this connector to start UID2 integrations, users need to have access to UID2 by submitting an access request through https://unifiedid.com/request-access.

Please work with your Trade Desk Account Manager or the Marketing Agency that owns the Trade Desk Account.

Once users have access to the UID2 service, they will have UID2 credentials that are an API key and a client secret to access the UID2.

You can get more information at https://unifiedid.com/docs/getting-started/gs-credentials#api-key-and-client-secret

AUID2 Base URL:

• In EU: https://euid.eu/docs/getting-started/gs-environments
• Others: https://unifiedid.com/docs/getting-started/gs-environments

Obtain Trade Desk Account Credentials

Users can find the advertiser ID and secret key from the management console within The Trade Desk. Open “Preferences”, and then “First Party Data Credentials” to view the advertiser ID and secret key.

• Advertiser ID: The advertiser ID for your account with The Trade Desk.
• Advertiser secret: The advertiser secret for your account with The Trade Desk.

Prepare normalized(and/or hashed) DII

The UID2 service accepts DII(email and phone number currently) to convert UID2. Each piece of identifying information should follow a specific data format for conversion. Please review the Terminology section or https://unifiedid.com/docs/getting-started/gs-normalization-encoding for more details.

How the Workflow works

The UID2 workflow automates the process of generating and maintaining UID2s. At a high level, the process is as follows:

• Input:
  • The workflow reads hashed or unhashed email addresses and phone numbers from source tables you specify within your Treasure Data database.
• Processing:
  • It communicates with the UID2 Operator Service to securely map your PII to UID2s.
  • The workflow also handles the critical task of "salt bucket rotation." Salt buckets are used to encrypt UID2s, and they are rotated periodically for security.
  • The workflow automatically identifies which UID2s have become stale due to rotation and remaps them.
• Output:
  • The final, valid UID2s are written to a central table in your database (ttd_uid2_ids)

Requirements and Limitations

There is a rate limit in the UID2 API endpoint; customers should consider limiting the number of records to process by setting the parameter uid2_limit_record

Setup and Configuration

Prepare Database Tables

The workflow requires several tables to operate. You must create some, while others are managed automatically by the workflow.

The API in your target database creates the necessary staging tables for API responses.

• ttd_bucket_resp: a staging table that hold the JSON response of salt bucket response
• ttd_uid2_resp: a staging table that hold the response of uid2 mapping

Or you can run the following SQL queries

CREATE TABLE IF NOT EXISTS "ttd_uid2_resp"("identifier" varchar);

CREATE TABLE IF NOT EXISTS "ttd_bucket_resp"("bucket_id" varchar);

Tables Automatically Created by the Workflow

• ttd_uid2_ids: The main output table containing your source data mapped to its current, valid UID2.
• ttd_uid2_ids_archive: An archive of records from ttd_uid2_ids.
• ttd_uid2_rqst: A staging table that holds the JSON payloads for batch requests sent to the UID2 Operator.

Create the Workflow via API

We can create a predefined UID2 using the API

API Request

curl -L 'https://integrations-gateway.us01.treasuredata.com/integration_workflow/workflows/uid2/' \
-H 'Authorization: {Your_TD_API_KEY}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "type": "uid2",
    "plugin_config": {
      "type": "uid2",
      "host": "https://operator-integ.uidapi.com",
      "apikey": "****",
      "secret": "****",
      "td_apikey": "****",
      "database": "your_database",
      "td_host": "api-production.treasuredata.com",
      "last_bucket_updated_time": "2025-04-28T07:02:00",
      "uid2_limit_records": 200000000,
      "enable_auto_format": true,
      "skip_limit": 500,
      "td_uid2_src_lst": [
        {
          "src_db": "src_db",
          "src_tbl": "src_tbl",
          "src_id_col": "contact_id",
          "src_dii_col": "email",
          "src_dii_typ": "EMAIL"
        }
      ],
      "custom_batch_size": 5000,
      "custom_email_filter_import_uid2_identifier": "regexp_like(identifier, '''^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$''')",
      "custom_phone_filter_import_uid2_identifier": "NOT regexp_like(identifier, '''^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$''')"
    },
    "workflow_config": {
      "project_name": "project_name",
      "revision": "revision",
      "schedule": "daily>: 07:00:00",
      "timezone": "America/Los_Angeles"
    }
  }'

API Response

{
  "id": "your workflow id",
  "name": "your workflow project name",
  "revision": "your workflow project revision",
  "createdAt": "2025-07-01T09:55:28Z",
  "updatedAt": "2025-07-03T07:23:35Z",
  "deletedAt": null,
  "archiveType": "s3",
  "archiveMd5": "z2c8UL26Vl+uJGfR9wPmKA==",
  "metadata": []
}

Parameters Reference

Workflow config

Plugin config

Dii source list

Monitor the Workflow

Once created, you can access and monitor the workflow from the TD Console:

1. Navigate to
2. Data Workbench > Workflows.
3. Search for the project_name you defined in the API call.

Please select the project to view its

Run History, where you can check the status, duration, and logs for each run.

Database Tables Explained

ttd_uid2_ids table

– Transactional Table – Main TTD UID2 Table

ttd_uid2_ids_archive – Transactional Table – Main UID2 Table

Same schema as ttd_uid2_ids table, except that the is_current will always have the value -1 to indicate archive records.

ttd_bucket_resp – Staging Table – For UID Salt Bucket Rotation API Responses

ttd_uid2_rqst – Staging Table – For UID Map API Requests

ttd_uid2_resp – Staging Table – For UID2 Map API Responses

Next Step

After the UID2 workflow runs successfully, users will have UID2 in the specified destination database.

• ttd_uid2_ids table has advertising_id. The value of advertising_id is UID2

Users incorporate the ID value into the audience data, then activate segmentation through the export integration with Trade Desk based on UID2 ID values.

https://docs.treasuredata.com/articles/#!int/the-trade-desk-export-integration

Appendix: Create the Workflow via Workflow

Instead of creating the UID2 workflow via API, the user can create the UID2 workflow by using the workflow.

Run a workflow

There are two options to define and run a workflow

1. Use the graphical interface on TD Console > Data Workbench > Workflows
2. Use the command-line interface of TD Toolbelt

While using the TD Console is more straightforward than the command-line interface, the TD CLI tool offers options for more complex configurations.

Refer here for more details about the syntax and usage of the TD Workflow

Workflow definition

_export:
  # Base configuration
  gateway_url: https://integrations-gateway.us01.treasuredata.com/integration_workflow/workflows/uid2/
  uid2_apikey: {uid2_apikey}
  uid2_secret: {uid2_secret}
  td_apikey: {td_apikey}
  host: {host}
  td_host: "api.treasuredata.com",

  
  # Database configuration
  database_name: {database_name}
  
  # Project configuration
  project_name: {project_name}
  revision: {project_revision}
  

+trigger_uid2_workflow:
  +prepare_request:
    echo>: "Preparing HTTP request to UID2 integration gateway"
    
  +execute_uid2_call:
    http>: ${gateway_url}
    method: POST
    headers:
      - Authorization: "TD1 ${td_apikey}"
      - Content-Type: "application/json"
    content: |
      {
        "type": "uid2",
        "plugin_config": {
          "type": "uid2",
          "host": "${host}",
          "apikey": "${uid2_apikey}",
          "secret": "${uid2_secret}",
          "database": "${database_name}",
          "td_apikey": "${td_apikey}",
          "td_host": "${td_host}",
          "last_bucket_updated_time": "2025-04-28T07:02:00",
          "uid2_limit_records": 2000000000,
          "enable_auto_format": true,
          "skip_limit": 500,
          "td_uid2_src_lst": [
            {
              "src_db": "source_database",
              "src_tbl": "email_table",
              "src_id_col": "129212",
              "src_dii_col": "userid",
              "src_dii_typ": "EMAIL"
            }
          ],
          "custom_batch_size": 5000,
          "custom_email_filter_import_uid2_identifier": "regexp_like(identifier, '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$')",
          "custom_phone_filter_import_uid2_identifier": "NOT regexp_like(identifier, '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$')"
        },
        "workflow_config": {
          "project_name": "${project_name}",
          "revision": "${revision}",
          "schedule": "daily>: 07:00:00",
          "timezone": "America/Los_Angeles"
        }
      }
    retry: 3
    store_content: true

  +echo_result:
    if>: ${http.last_content != null}
    _do:
      echo>: "Response details: ${http.last_content}"
    
+error_handling:
  _error:
    echo>: "Error triggering UID2 workflow. Check logs for details."

Parameters Reference

Workflow config

Plugin config

Dii source list

About EUID

European Unified ID

EUID is an open-source, standalone solution with its own unique namespace that builds on the UID2 framework. The main differences between UID2 and EUID result from more stringent European and UK data protection laws relating to consent practices, rights for data subjects, and obligations between participants. Otherwise, EUID follows the same guiding principles as UID2.

Reference: https://euid.eu/docs/intro

All EUID, use a different base URL: https://euid.eu/docs/getting-started/gs-environments