The Trade Desk Connector API

The Trade Desk Connector API lets an unattended integration deliver audiences to The Trade Desk (TTD) and manage the taxonomy third-party audiences are sold from. A person signs in once to create an API key, and the integration uses that key from then on. Complete the prerequisites and set up API access on this page before you follow any of the guides.

Choose a guide

First-party delivery

Deliver an audience into one advertiser’s own seat. No taxonomy, no review by TTD.

Third-party delivery

Deliver an audience to TTD’s marketplace, where the buyers you choose can purchase it.

Taxonomy management

Build, price, and maintain the taxonomy third-party audiences are sold from.

First-party and third-party delivery compares the two delivery models.

Prerequisites

What you need depends on the guide you follow:

Prerequisite	First-party	Third-party	Taxonomy
API key	✓	✓	✓
TTD Brand ID on your connector profile	✓	✓	✓
Sub-Provider ID, where TTD requires one		✓	✓
Taxonomy element for the audience		✓
Advertiser ID and secret key	✓

API key

Create the key under Settings → API Keys with read and write on datasets and connections, write on uploads, and read on app_profiles. See API Keys for the procedure and the Permissions Reference for what each resource covers. Create it from a shared team account rather than a personal login, so the integration keeps working when someone changes roles. Keys expire in at most 365 days, so plan on rotating yours once a year.

Brand ID

Narrative is the registered data provider at The Trade Desk, and your Brand ID is a brand under Narrative’s provider account. TTD issues it, so you cannot create one yourself. Ask your Narrative relationship manager or your TTD account representative. The Brand ID is stored on your connector profile. The connector’s GET /profiles returns the profile with its Brand ID and Sub-Provider ID; see Find your connector profile. Taxonomy synchronization is refused for a profile with no Brand ID.

Sub-Provider ID

Where TTD requires one, the connector sends the Sub-Provider ID when it creates each taxonomy element in TTD. It cannot be added to an element afterward, so have it on your profile before your first synchronization. Your Narrative relationship manager sets it up.

Taxonomy element

Every third-party audience is a buyable element in your taxonomy, and the element carries the price and who can buy it. Your first taxonomy needs TTD’s approval before anything sells, so start it early with Taxonomy management.

Advertiser ID and secret key

First-party delivery goes into one advertiser’s seat, so you need that advertiser’s TTD Advertiser ID and secret key from whoever owns the seat.

Set up API access

The guides talk to two hosts, and both accept the same credential, Authorization: Bearer <your API key>:

Host	Base URL	Handles
Narrative API	`https://api.narrative.io`	Datasets, uploads, connections
Trade Desk connector	`https://thetradedesk.narrativeconnectors.com`	Connector profile, schema validation, taxonomy elements, synchronization, advertiser registration, delivery statistics

Confirm that both answer before you build anything:

curl -s https://api.narrative.io/company-info/whoami \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"id":1234}

curl -s https://thetradedesk.narrativeconnectors.com/whoami \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → 1234

Both must return your company ID. The connector returns it as a bare number. A 403 from the first call means the key was not created under Settings → API Keys. Application credentials do not work with these guides.

API keys contain characters that shells mangle. Read the key from a file or an environment variable rather than pasting it inline.

What the connection does

A connection’s quick_settings pick the delivery model and set how the connection delivers. The fields depend on the interface.

First-party delivery (`first_party`)

Field	What it does	Allowed values	Default
`first_party_data_type`	Selects first-party delivery	`first_party_external`	None. Required
`advertiser_ids`	The advertisers whose seats receive the audience	A list of one or more The Trade Desk advertiser IDs	None. Required
`data_segment_names`	The first-party segment each advertiser receives. The connection creates the segment if it does not exist	A list of one or more segment names	None. Required
`targeting_time_to_live_in_minutes`	How long The Trade Desk keeps each delivered identifier in the segment	1 or more	129600 (90 days)
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`false`

Third-party delivery (`third_party_v2`)

Field	What it does	Allowed values	Default
`third_party_data_type`	Selects third-party delivery	`third_party`	None. Required
`provider_elements`	The taxonomy elements that receive the audience	A list of one or more `{"provider_element_id": "<uuid>", "display_name": "<name>"}` objects	None. Required
`targeting_time_to_live_in_minutes`	How long The Trade Desk keeps each delivered identifier in the element	1 or more	129600 (90 days)
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`false`

Existing and new rows

A connection delivers every snapshot written to the dataset after the connection is created. The historical_data_enabled quick setting decides whether the connection also delivers data that was already in the dataset when you created it:

With historical_data_enabled set to true, the connection first delivers data already in the dataset, then keeps delivering new snapshots as they land.
With historical_data_enabled set to false, the connection delivers only snapshots written after it was created.

How far back the first delivery reaches depends on the connector, and each connector’s guide states it. For The Trade Desk, historical_data_enabled delivers everything in the dataset when the connection is created. After that, each new snapshot is delivered as it lands. A snapshot from an append write sends the rows it added. A snapshot from an overwrite write sends the whole dataset. Each delivered identifier carries targeting_time_to_live_in_minutes. The Trade Desk keeps the identifier for that long, and a later delivery of the same identifier sends it with a fresh time to live. The connection never removes identifiers, so rows that an overwrite drops stay in the segment until their time to live runs out. Overwriting the dataset on a schedule sends every member again, which keeps the whole audience current.