Integrating The Trade Desk to Clarisights
The Trade Desk (TTD) is a global ad-buying DSP for programmatic display, video, audio, native, and CTV. Connecting TTD to Clarisights lets you analyze DSP spend, bids, impressions, click-through and view-through conversions, and creative-level performance side-by-side with your other paid channels.
At a glance
| Authentication | TTD login (email + password) with API access + a scheduled report set up in TTD's My Reports |
| Permissions needed | API access on the TTD user, and read access to the Partner / Advertiser you're connecting |
| Account discovery | Per-advertiser. You provide the Partner ID and a Schedule Name; Clarisights connects one advertiser at a time, but a single Partner can have many advertisers |
| Data freshness | Daily (or weekly — whatever cadence the TTD scheduled report uses) |
| Lookback window | Whatever the scheduled report exposes; typically a rolling daily window. Clarisights pulls each new report execution as it completes |
| Backfill on connect | Subject to what's available in My Reports execution history (last completed runs) |
| Timezone | Per-account, taken from TTD; the report's Date column is parsed and converted into account timezone on ingest |
| Currency | Advertiser currency (Adv Currency); converted to your reporting currency by Clarisights |
| Levels supported | Account · Campaign · Ad Group · Ad (Creative) |
| Limited rollout | No |
Prerequisites
A TTD login (email + password) with API access enabled by your TTD admin. Ask TTD support if you're unsure whether your seat has API access.
The Partner ID for the advertiser you want to connect (visible from the TTD dashboard URL or partner switcher).
Permission to create a scheduled report on the advertiser in TTD's My Reports.
Steps to Connect
Step 1 — Set up the report template in TTD
Open My Reports in your TTD dashboard and create a new report template with the following fields and metrics. Field names must match exactly — Clarisights parses the report by header name.
[TODO: Screenshot of TTD My Reports template editor]
Fields (Dimensions):
Advertiser ID
Advertiser
Advertiser Currency Code
Campaign ID
Ad Group ID
Creative ID
Ad Format
Date
Metrics:
Bids
Clicks
Impressions
Advertiser Cost (Adv Currency)
Data Cost (Adv Currency)
Conversion metrics: add each conversion event as two separate metrics — the click-through and view-through versions. Example: 01 - Click Conversion and 01 - View Through Conversion. Do not use the combined Click + View Through metric — Clarisights expects them to be split so click and view paths can be reported separately.
[TODO: Screenshot of TTD report metrics with split click vs. view conversions]
Step 2 — Schedule the report
Schedule the report for recurring delivery. Note the Schedule Name exactly as TTD shows it — the default is {Advertiser} | {Report Name}. You'll paste this into Clarisights in Step 3.
Configure the schedule with these settings (the ingest will reject the file otherwise):
Date Format: Sortable
Numeric Format: US
Recurring Scheduling: select Schedule for recurring delivery and pick a daily or weekly cadence
[TODO: Screenshot of TTD scheduling page with Sortable / US / Recurring options]
⚠ Data not appearing or appearing malformed → The most common cause is non-Sortable dates or non-US numeric format. Edit the schedule, change those two settings, and Clarisights will pick up the next execution automatically.
Step 3 — Find your Partner ID
From the TTD dashboard, switch into the partner that owns the advertiser. The Partner ID appears in the URL (and in the partner switcher dropdown).
[TODO: Screenshot of TTD partner dropdown showing Partner ID]
Step 4 — Connect in Clarisights
In Clarisights, go to the Integrations page, search for The Trade Desk, and click Add User. Provide:
Email + Password — the TTD login with API access
Partner ID — for the advertiser you're connecting
Schedule Name — matching the report you scheduled in Step 2
Click Connect Source. Clarisights authenticates against TTD's /v3/authentication endpoint, queries the Partner's advertisers, and links the scheduled report.
[TODO: Screenshot of TTD connector form in Clarisights]
⚠ Authentication failed (401 / 403) → The TTD seat does not have API access. Ask your TTD admin to enable it, or use a different login.
⚠ No reports found → The Schedule Name doesn't match an existing scheduled report under the Advertiser, or the report has not yet completed an execution. Verify the name in TTD's My Reports and wait for the first run to finish.
Verify the connection
Go to Integrations → The Trade Desk. The connected advertiser should show with its name, timezone, currency, and Schedule Name.
First data appears after the first scheduled report execution completes (usually within ~24 hours of connecting). Each subsequent execution is pulled, parsed, and ingested automatically.
Quick start: create a new report, add The Trade Desk as the data source, and add Account · Campaign · Ad Group · Impressions · Clicks · Advertiser Cost.
Data available
Hierarchy
How TTD's native levels map to the standard Clarisights levels:
Native level (TTD) | Clarisights level |
Partner | Used at connect time only (one Partner can map to many advertisers / accounts) |
Advertiser | Account |
Campaign | Campaign |
Ad Group | Ad Group |
Creative | Ad |
Dimensions
Dimension | Level | Description |
Account / Account ID | Account | TTD Advertiser name and ID |
Advertiser Currency Code | Account | Currency the advertiser reports in |
Schedule Name | Account | The TTD My Reports schedule that feeds this account |
Campaign / Campaign ID | Campaign | Campaign name and ID |
Campaign Status | Campaign | TTD configured status (Active / Paused / Archived) |
Daily Budget / Total Budget | Campaign | Configured pacing budgets |
Ad Group / Ad Group ID | Ad Group | TTD Ad Group name and ID |
Ad Group Status | Ad Group | Configured status |
Base Bid CPM / Max Bid CPM | Ad Group | Bid configuration |
Ad / Creative ID | Ad | Creative name and ID |
Creative Status | Ad | Configured status |
Creative Type | Ad | Display, video, audio, native, etc. |
Ad Format | Ad | TTD ad format on the creative |
Image / Preview | Ad | Creative preview rendered as an image where available |
Metrics
Metric | Category | Description |
Bids | Traffic | Total bids submitted |
Impressions | Traffic | Won impressions |
Clicks | Traffic | Total clicks |
Advertiser Cost | Cost | Total advertiser cost (Adv Currency) |
Data Cost | Cost | Cost of audience / data layered onto bids (Adv Currency) |
Media Cost | Cost | Pure media cost (Adv Currency) |
TTD Cost / TTD Margin | Cost | TTD platform cost and margin (Adv Currency) |
Additional Fee Cost / Fee Features Cost | Cost | Other fees (Adv Currency) |
Predictive Clearing Savings | Cost | Savings from TTD's Predictive Clearing |
CTR / CPM / CPC | Derived | Click-through rate, cost per mille, cost per click |
Win Rate | Derived | Impressions / Bids |
Click Through Conversions / Click Through Revenue | Conversions | Per-conversion-event metric — one set per conversion goal you add to the report (01, 02, 03…) |
View Through Conversions / View Through Revenue | Conversions | Per-conversion-event metric — one set per conversion goal you add to the report |
Limitations & known constraints
Schedule-driven: ingestion is gated by your TTD scheduled report. Pause the schedule and Clarisights stops receiving new data until the next execution.
Strict report shape: the report's column headers, date format (Sortable), and numeric format (US) must match this guide exactly. Any drift causes parse failures.
Conversions must be split: combined click+view conversion metrics aren't ingested. Add each goal as separate Click Conversion and View Through Conversion metrics.
One advertiser per connector: each connector handles one TTD advertiser. To onboard multiple advertisers under the same Partner, add one connector per advertiser.
Creative auto-fetch: if a row references a creative not yet in Clarisights, we fetch it from TTD's
/creative/{id}endpoint on the fly. If the creative is missing from TTD's API entirely, the row is dropped and reported on Sentry.
Operating notes
Refresh schedule: driven by your TTD My Reports cadence (daily or weekly). Each completed execution is downloaded, sanitized, and ingested.
Lookback: depends on the date range your scheduled report covers (typically rolling daily). Adjust the schedule in TTD if you need a longer window.
Multi-advertiser under one Partner: connect each advertiser separately; they share the same TTD login but have independent Schedule Names.
Currency conversion: the advertiser-currency cost values are stored on ingest and converted to your Clarisights reporting currency.
Credential rotation: re-authenticate any time from Integrations → The Trade Desk → Edit User. The access token is short-lived (TTD requires
TokenExpirationInMinutes) and is refreshed automatically.
Need help?
When contacting support from the in-app messenger, please include:
The integration name, advertiser, and Partner ID
The exact Schedule Name in TTD
The exact error message or screenshot
The step where the issue occurred
When the issue started