Introduction & Scope

DataX is an aggregate Yahoo Ad Tech infrastructure that hosts various components that enable Yahoo Ad Tech to exchange data with its external partners in a secure, automated and scalable manner. This guide covers the partner-facing RESTful API that enables this exchange.

At a Glance

Partners can exchange structured data against user identifiers such as cookies, user-matchedids, households, and so on, and share information, like segment qualifications, user attributes, seed segments, audience models, using the DataX infrastructure and API.

Current Scope

The current version of the DataX API supports these primary functions:

1. Importing taxonomy.

2. Ingesting user/audience data against pre-matched ids.

Important

In the future, DataX will also provide support for ingesting and exporting user match-related data, audience models, and so on.

APIs to Get Started

The following two primary API calls and their respective JSON representations will enable you to get up and running with DataX, and start exporting regular updates to the data that you share with Yahoo Ad Tech.

These two primary APIs are:

1. POST /taxonomy – Export a Taxonomy of all the data that you share with Yahoo Ad Tech.

2. POST /audience – Export syndicated/custom/advertiser segments and attributes.

Other APIs

This specification covers a few other APIs as well:

1. GET /taxonomy – Fetch your current taxonomy.

2. PUT /taxonomy/append/{id} – Append taxonomy nodes

3. PUT /taxonomy/replace/{id}- Replace existing taxonomy node

4. PUT /taxonomy/move/{id-a}/{id-y} – Move taxonomy node

5. DELETE /taxonomy/{id} – Delete node from taxonomy

6. POST /audience/segment/{id} – An alternative to POST /audience

7. POST /audience/attribute/{id} – An alternative to POST /audience

8. POST /audience/opt-out – To opt out users completely from data segments.

9. GET /audience – To look at all your recently uploaded data.

Document Structure

As you navigate the topics described in the DataX API, you’ll find references to links that are made available in response to most of the above POST/PUT calls: for example, links with statistics on the data that you uploaded, their current status, validation reports, links to re-submit previously failed data sets, and so.

These are provided to help ease your interactions with DataX and help you automate your exports to Yahoo Ad Tech.

In the next sections of the guide, you’ll find a high-level overview of the API call flow, followed by a few simple examples without diving into too many details. Subsequent sections detail every aspect of the API, data formats, permissible values, precise API call examples, and so on. Each section provides a quick executive summary and helps set the stage for a deep dive into the rest of the guide.