Delivering First-Party Audiences to The Trade Desk via the API

This guide shows you how to build an unattended integration that uploads an audience to Narrative and delivers it into one advertiser’s own seat at The Trade Desk (TTD). A person signs in once to create an API key, and the integration uses that key from then on. First-party delivery needs no taxonomy and no review by TTD. To list an audience in TTD’s marketplace instead, see Third-party delivery via the API. First-party and third-party delivery compares the two models. Before you start, complete the prerequisites and set up API access.

1. Create the dataset

Your schema decides whether The Trade Desk will accept the audience, so settle it before you upload anything. The dataset must carry at least one identifier the connector recognizes, and each one is an object with a value property inside it. See Supported identifiers for the full list.

curl -X POST https://api.narrative.io/datasets \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 In-Market Auto",
    "description": "Audience for The Trade Desk",
    "write_mode": "overwrite",
    "schema": {
      "file_config": { "type": "json" },
      "type": "object",
      "properties": {
        "android_advertising_id": {
          "type": "object",
          "display_name": "Android Advertising ID",
          "properties": {
            "value": { "type": "string", "display_name": "Value" }
          }
        }
      }
    }
  }'

write_mode is overwrite or append. file_config.type is json for JSON Lines, parquet, or flat for CSV. Both fields are required. The dataset comes back pending. Record its ID.

You do not need to supply UID2. The connector generates UID2 tokens from hashed email addresses automatically.

2. Activate the dataset

curl -X POST https://api.narrative.io/datasets/{dataset_id}/activate \
  -H "Authorization: Bearer $NIO_API_TOKEN"

Activation locks the schema. You cannot change it afterward, so activate only once the shape is settled.

3. Upload your file

Request an upload URL, then send the file straight to storage:

curl -X POST https://api.narrative.io/uploads/audiences/q3-auto.json \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"path": "a1b2c3....json", "url": "https://...", "expiry": "..."}

curl -X PUT "<url from the response>" --upload-file ./q3-auto.json

The upload URL is valid for 30 minutes and carries its own signature, so send no authorization header with the PUT.

A signed-URL upload supports a single file of up to 3 GB. For larger files, or for files that another system delivers on a schedule, write them to a managed bucket instead: see Ingesting Files from a Managed S3 Bucket. That replaces this step and the next one.

Keep the path from the response. Narrative assigns its own storage path, which will not match the one you requested, and the next step needs Narrative’s path rather than yours.

4. Ingest the file

curl -X POST https://api.narrative.io/datasets/{dataset_id}/upload \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_file": "a1b2c3....json"}'

Ingestion runs in the background. Watch the record count on the dataset to know when it has finished:

curl -s https://api.narrative.io/datasets/{dataset_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → .stats.active_dataset_stored_records

The count moves from zero to your row count, typically within a couple of minutes.

5. Confirm The Trade Desk accepts the dataset

curl -s https://api.narrative.io/datasets/{dataset_id}/interfaces \
  -H "Authorization: Bearer $NIO_API_TOKEN"

Look for The Trade Desk ("app_id": 11) in the accepted list, under the interface your delivery model uses: first_party for first-party, third_party_v2 for third-party. See Delivery interfaces for what each interface does. If The Trade Desk appears under rejected instead, the response tells you what is missing:

{
  "app_id": 11,
  "interface_id": "third_party_v2",
  "details": {
    "valid": false,
    "errors": { "required": "required property 'android_advertising_id' not found" }
  }
}

That is a schema problem. Because the schema is locked at activation, fixing it means creating a new dataset. This endpoint returns 404 until the dataset is activated.

Mapping identifiers

Mapping your identifier column to a Rosetta Stone attribute is not required for The Trade Desk to accept the dataset. Acceptance is decided by your schema alone. Map anyway: normalized attributes make the dataset usable across other destinations and Narrative features. Mapping needs a data sample first:

curl -X POST https://api.narrative.io/datasets/{dataset_id}/request-sample \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# poll https://api.narrative.io/jobs?dataset_id={dataset_id}
# until the datasets_sample job completes (roughly 8 minutes)

curl -X POST https://api.narrative.io/mappings/companies/{company_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": 12345,
    "attribute_id": 70,
    "mapping": {
      "type": "object_mapping",
      "property_mappings": [
        { "path": "value", "expression": "android_advertising_id.\"value\"" }
      ]
    }
  }'

value is a reserved keyword in mapping expressions, so quote it. Attribute IDs for the common mobile identifiers: mobile_id_unique_identifier is 68, apple_idfa is 69, android_advertising_id is 70.

6. Find your connector profile

Your profile holds your Brand ID and backs every delivery.

curl -s "https://api.narrative.io/installations?app_categories=destination_connector" \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# find the record with "app_id": 11 and note its "id"

curl -s https://api.narrative.io/installations/{installation_id}/profiles \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → [{"id": "f692fb18-...", "status": "enabled", ...}]

Record the profile ID. Its status must be enabled. If you have no profile yet, create one in the Narrative UI under Objects → Installed Apps → Trade Desk Connector and enter your Brand ID there.

7. Register the advertiser

Register each receiving advertiser once. The registration holds the credentials the connector uses to deliver into that advertiser’s seat.

curl -X POST https://thetradedesk.narrativeconnectors.com/advertisers \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Motors",
    "ttd_id": "<their TTD advertiser id>",
    "secret": "<their secret key>"
  }'

ttd_id is the advertiser’s ID in The Trade Desk. You use the same value in the next step.

8. Deliver the audience

Create a connection joining the dataset, the profile, and the advertiser:

curl -X POST https://api.narrative.io/v2/connections \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "connections_dataset",
    "dataset_id": 12345,
    "profile_id": "f692fb18-9d47-4c2a-b1e6-3c5f8a0b7d21",
    "quick_settings": {
      "type": "first_party",
      "first_party_data_type": "first_party_external",
      "advertiser_ids": ["<their TTD advertiser id>"],
      "data_segment_names": ["In-Market Auto Q3"],
      "targeting_time_to_live_in_minutes": 129600,
      "historical_data_enabled": true
    }
  }'

Both type fields are required. The outer one identifies what you are connecting, and the inner one selects the delivery interface. Always send them. advertiser_ids takes the advertiser’s Trade Desk ID, the value you registered as ttd_id, not the identifier Narrative returns for the registration record. A delivery to an advertiser the connector cannot resolve fails with an error naming that advertiser. data_segment_names is the name the segment carries in the advertiser’s seat. It is free text, not a taxonomy element. targeting_time_to_live_in_minutes is how long a delivered identifier stays active in TTD before expiring, and it defaults to 90 days. The clock rides on every record, so each delivery renews it. See Audience membership duration for the full behavior.

historical_data_enabled decides whether data already in the dataset is delivered or only rows written after the connection is created. It cannot be changed once the connection exists.

See First-party connection settings for every field.

9. Confirm the connection

curl -s "https://api.narrative.io/v2/connections?dataset_id=12345" \
  -H "Authorization: Bearer $NIO_API_TOKEN"

The response lists the first_party connection you created. Once delivery runs, the segment appears in the advertiser’s seat under the name you gave it in data_segment_names, as though the advertiser had uploaded it themselves.

Keeping the audience current

Write new data to the dataset. The connection keeps running, so new rows reach the advertiser’s seat without further calls. Refresh the dataset more often than the membership duration. Members that no delivery renews expire after targeting_time_to_live_in_minutes, and your source dataset must refresh at least every 90 days. advertiser_ids takes a list, so one connection can deliver the audience to several registered advertisers.

Troubleshooting

Dataset and upload problems

Symptom	Cause	Fix
`403` on `/company-info/whoami`	The key was not created under Settings → API Keys	Create one there. Application credentials do not work with this flow
`400 Missing required field .write_mode` or `.schema.file_config`	Both are required on dataset creation	Add them
`400 file not found` on ingest	You sent the path you requested rather than the one Narrative returned	Use the `path` from the upload response
Record count stays at zero	The file did not match the schema	Check that the format matches `file_config.type` and that field names match your schema exactly
`404` on `/datasets/{id}/interfaces`	The dataset is not activated yet	Activate it first
The Trade Desk listed as rejected	The schema has no recognized identifier in the expected shape	Read `details.errors`, then create a new dataset with a corrected schema
`400 No sample is available` on mapping	Mapping needs a data sample	`POST /datasets/{id}/request-sample`, wait for the job, retry

Delivery problems

Symptom	Cause	Fix
Delivery fails with an error naming an advertiser	The ID in `advertiser_ids` is not a registered TTD advertiser ID	Register the advertiser with `POST /advertisers`, and use its `ttd_id` in `advertiser_ids`
Members disappear from the segment	No delivery renewed them within the membership duration	Refresh the dataset more often than `targeting_time_to_live_in_minutes`

Getting help

Contact your Narrative relationship manager with your company ID, the dataset ID, and the failing request and response. For questions about the advertiser’s seat or credentials, the advertiser’s TTD account representative is the faster path.

Third-party delivery via the API

List an audience in TTD’s marketplace instead

The Trade Desk Connector

Full settings reference, identifiers, and status vocabularies

Connector Interfaces

Why a dataset connects to an interface rather than a connector

API Keys

Create and rotate keys for programmatic access

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Connector APIs

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Delivering First-Party Audiences to The Trade Desk via the API

1. Create the dataset

2. Activate the dataset

3. Upload your file

4. Ingest the file

5. Confirm The Trade Desk accepts the dataset

Mapping identifiers

6. Find your connector profile

7. Register the advertiser

8. Deliver the audience

9. Confirm the connection

Keeping the audience current

Troubleshooting

Dataset and upload problems

Delivery problems

Getting help

Third-party delivery via the API

The Trade Desk Connector

Connector Interfaces

API Keys

​1. Create the dataset

​2. Activate the dataset

​3. Upload your file

​4. Ingest the file

​5. Confirm The Trade Desk accepts the dataset

​Mapping identifiers

​6. Find your connector profile

​7. Register the advertiser

​8. Deliver the audience

​9. Confirm the connection

​Keeping the audience current

​Troubleshooting

​Dataset and upload problems

​Delivery problems

​Getting help

​Related content

Third-party delivery via the API

The Trade Desk Connector

Connector Interfaces

API Keys

1. Create the dataset

2. Activate the dataset

3. Upload your file

4. Ingest the file

5. Confirm The Trade Desk accepts the dataset

Mapping identifiers

6. Find your connector profile

7. Register the advertiser

8. Deliver the audience

9. Confirm the connection

Keeping the audience current

Troubleshooting

Dataset and upload problems

Delivery problems

Getting help

Related content