Skip to main content
This guide shows you how to build, price, and maintain your taxonomy at The Trade Desk (TTD) over the API, with nobody signed in. The taxonomy is where third-party audiences are listed: each audience is an element in it, and the element sets who can buy the audience and at what price. To attach data to an element and deliver it, see Third-party delivery via the API. First-party delivery uses no taxonomy; see First-party delivery via the API. Before you start, complete the prerequisites and set up API access.

​
1. Plan the tree

A taxonomy is a tree of taxonomy elements. A folder (buyable: false) organizes. An audience (buyable: true) is what buyers purchase, and it carries the dataset and the rate cards.
Name the root for your audience product. Create it even if you never plan to sell openly. It is the level everything else hangs from, and reshaping the top of the tree after audiences are live cannot be cleanly undone. Keep one-to-one deals under their own folder. TTD suggests a folder such as Custom Audiences for audiences priced for a single advertiser or partner. It is a naming convention, not a special element type. Price every audience on the audience itself. TTD stopped passing rates down from parent folders to new segments in March 2024, so each buyable element needs its own rate card.

​
2. Create the folders

One endpoint creates every element. buyable is what separates a folder from an audience.
Record the element_id that comes back. Child elements name it as parent_element_id. Then create Custom Audiences the same way, with parent_element_id set to the root’s element_id.

​
3. Create an audience

An audience is the same call with buyable: true, a parent, a dataset, and the rate cards that decide who can buy it and at what price.
The connector checks each dataset’s schema against The Trade Desk when you attach it. To prepare a dataset, follow steps 1 through 5 of Third-party delivery via the API.

​
Who can buy it

Each entry in data_rates sets a price and who gets it: One element can carry several rates, and the most specific rate that applies to a buyer wins. To price one audience differently for different buyers, add one entry per advertiser or partner:
Advertiser and partner IDs come from your TTD account representative, and they go straight onto the rate card. You do not register them with Narrative first.

​
Setting the rate

Every rate carries both cpm_rate and percent_of_media_cost_rate, whatever its rate_type. rate_type is cpm, percent_of_media_cost, or hybrid, and TTD asks for hybrid on marketplace segments. A rate of 0.0 is valid if you provide the data at no cost. A rate with a CPM below $0.25 needs TTD’s approval before it applies.

​
4. Revise before you synchronize

Elements you create are drafts, and nothing reaches The Trade Desk until you synchronize. Until then you can change anything with PUT. It replaces the whole element, so send every field:
Once an element is active, its rates are fixed. A PUT that changes them is rejected with data rates cannot be updated for active taxonomy element, while one that sends the same rates again goes through. The display name, description, and datasets can still change, and a new name or description is sent on to TTD. Put every buyer you expect on the element when you create it. Changing the price or the buyers of a live audience is not self-service: ask your Narrative relationship manager, who arranges it with The Trade Desk.

​
5. Synchronize

The request moves through pending and in_progress to completed or failed. Its jobs object counts the work in three parts: elements created in TTD (create_taxonomy_elements), rate batches (create_data_rate_batches), and delivery connections for attached datasets (create_connections). Failures carry per-element detail. Two rules shape how you automate this:
  • Synchronization publishes every draft in your account, not only the element you just changed. Create everything you want published, then synchronize once.
  • Only one synchronization runs at a time. A second request while one is pending or in progress is rejected. A loop that creates one audience and synchronizes it breaks on its second pass, so batch your changes instead.
A request with no drafts to send is rejected with Nothing to synchronize, and one from a profile with no Brand ID is refused.

​
6. Wait for approval

Each element reports two statuses, and an audience sells only once it is active and its compliance_status is Approved:
  • status is the element’s lifecycle in Narrative, from draft to pending to active.
  • compliance_status is TTD’s review, from NotInQueue to Pending to Approved or Denied.
See Element status and approval for every value. Narrative re-checks review status with TTD every 30 minutes, so a decision on their side can take up to half an hour to appear. Poll on that cadence, because anything faster tells you nothing new.
Plan for lead time on your first taxonomy. Ask your Narrative relationship manager about turnaround for elements you add later, because that answer decides whether your integration must treat each new audience as pending for a while or only the first ones.

​
7. Maintain the taxonomy

Add audiences by repeating step 3, then synchronizing. Batch several new elements into one synchronization. Refresh who is in an audience by writing to its dataset. The delivery connection keeps running, so you do not touch the element or its price. See Keeping the audience current. Watch the match rate. Each element’s statistics reports received_ids_count, the identifiers Narrative sent, and active_ids_count, the subset TTD matched. See Confirm delivery. Create a new audience rather than reworking an old one when the price changes, the schema changes, or it is a different audience for a different buyer. A live element’s rates are fixed, so a new element is the only self-service way to price separately. Retiring a live audience is not self-service. Contact your TTD Technical Account Manager and your Narrative relationship manager. Removing a custom segment from a named buyer requires 30 days’ advance notice to that buyer.
DELETE /taxonomies/elements/{element_id} archives the element and everything beneath it in Narrative only. Nothing is sent to The Trade Desk, and an element that is already live there stays buyable. Use it to clean up drafts, not to retire an audience.

​
Taxonomy endpoints

All on https://thetradedesk.narrativeconnectors.com.

​
Troubleshooting

​
Getting help

Contact your Narrative relationship manager with your company ID, the element ID, and the failing request and response. For review status, Brand ID, advertiser IDs, or partner IDs, your TTD account representative is the faster path.

​
Related content

Third-party delivery via the API

Attach data to an element and deliver it

First-party delivery via the API

Deliver into one advertiser’s own seat, with no taxonomy

The Trade Desk Connector

Full settings reference, identifiers, and status vocabularies

API Keys

Create and rotate keys for programmatic access