Taxonomy Management

Using the Audience Segments API, customers and data providers have control to onboard and activate the data they need to target in MediaMath Platform. As it's a self-service solution, turnaround time for updates is reduced from business days to minutes. The API is built using industry standard, open source REST APIs and is a scaleable way to handle all requests for both global and permissioned taxonomies. The service brings transparency to data activation at MediaMath, allowing customers and data providers oversight of relevant 1st and 3rd party audience data sets as well as the permissioning of those data sets.

There are two ways to expose the data onboarded via server-to-server within MediaMath Platform:

• Taxonomies
  • These can be global, meaning all MediaMath customers will have access to the segments within the taxonomy in MediaMath Platform.
  • These can be permissioned so that only select MediaMath customers have access to the segments within the taxonomy in MediaMath Platform.
• External Data Segments
  • These represent a single segment and are always permissioned.
  • These are also referred to as Data Pixels.

It's possible to use both methods to achieve a mix of global and permissioned taxonomies & external data segments to suit your needs and the needs of your customers.

Note: The S2S data transfer is the same for both global and permissioned taxonomies, as well as external data segments.

Taxonomies are presented in MediaMath Platform as a hierarchical tree, where the first node (root node) is the data provider's name. Within the tree, media traders can expand selections of categories of segments and view an estimated audience size (the number of unique users) and a CPM price (USD by default).

In this view, the Audience Targeting view has been annotated to show the elements of a taxonomy:

Similar to global taxonomies, permissioned taxonomies are also presented in MediaMath Platform as a hierarchical tree, where the first node (root node) is the data provider's name. Within the tree, media traders can expand selections of categories of segments and view an estimated audience size (the number of unique users) and a CPM price (USD by default).

Permissioned taxonomies can include first and/or third party segments and are 'permissioned' or shared with specified entities, organizations, agencies and/or advertisers in MediaMath Platform.

As all taxonomy management utilizes the same underlying MediaMath API, the information shared in this section applies to both global and permissioned taxonomies, with the exception of the visibility of the taxonomy & permissioning.

Utilizing the API requires the data provider be set up as a data vendor in our system and that MediaMath act as a clearinghouse for all transactions. For third-party data providers, you'll work out terms with our partnerships team; for customers sharing first-party data, the revenue share will typically be set at 0 by our partnerships team.

Each data provider has a default revenue share, mutually agreed upon with the partnerships team; however, this default revenue share value can be overridden at a taxonomy level. For example, if a customer wants to target segments in MediaMath Platform at a rate which they have pre-negotiated with you, their data vendor, the customer's specific rate may require the use of a revenue share different from the default revenue share originally agreed upon between you & MediaMath. To facilitate this, you as the data provider, can create a permissioned taxonomy for the customer and work with the partnerships team to set a revenue share that relates to that specific taxonomy.

To override a revenue share at the taxonomy level, create the taxonomy with permissions and contact MediaMath Support with the following information:

• the Taxonomy_ID,
• the desired taxonomy-level revenue share.

Our team will respond once they have updated the revenue share for the specified taxonomy.

All v3.0 endpoints require a Bearer token in the Authorization header, obtained through the standard MediaMath OAuth flow — see the Authentication guide for how to obtain and refresh one. Endpoint paths below are relative to https://api.mediamath.com/api/v3.0/.

curl --location 'https://api.mediamath.com/api/v3.0/<endpoint>' \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json'

Taxonomies — these are the endpoints your integration will spend most of its time in. Full schemas are in the Campaigns API v3.0 reference.

Vendor configuration and grants — these are provisioned and maintained by Infillion on your behalf. You will not normally call them, but they explain most validation errors you may hit.

Every taxonomy create or update passes three checks before processing:

1. Vendor audience config — does vendor_id have a configuration? This defines the owning organisation, bidder code, default revenue share and creation limit. (Managed by Infillion.)
2. Organisation grants — are grants configured for the owning organisation? These define which organisations, agencies and advertisers you may permission a taxonomy to. (Managed by Infillion.)
3. Request permissions — is everything in your permissions block inside that grant scope, and are the visibility rules satisfied? (Entirely client-controlled.)

Before your first create, read your grants with GET /grants/{org_id}?with=entity_info and treat them as the outer boundary for every permissions block you send. Requesting a subset of the grant scope always passes; anything outside it always fails.

Creating a taxonomy — POST /audience_taxonomies:

curl --location 'https://api.mediamath.com/api/v3.0/audience_taxonomies' \
   --request POST \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --data '{
     "vendor_id":   1024,
     "visibility":  "RESTRICTED",
     "use_hash":    true,
     "permissions": {
       "organizations": [2001],
       "agencies":      [3101],
       "advertisers":   [45001]
     },
     "taxonomy": {
       "name":     "Acme Data - (Private) - Interest Taxonomy",
       "buyable":  false,
       "children": [
         { "name": "Sports", "code": "sports_root",
           "buyable": true, "retail_cpm": 2.5, "children": [] },
         { "name": "Travel", "code": "travel_root",
           "buyable": true, "retail_cpm": 3.2, "children": [] }
       ]
     }
   }'

The response is an HTTP 200 with a data object containing the created taxonomy, its generated taxonomy and node IDs, the applied revenue_share_pct, visibility and vendor information. Unlike the legacy DMP API, which returned a temporary ID before the segment had synced, v3.0 returns the actual audience segment IDs assigned to Strategies immediately in this response. Store them — they are the handle for every subsequent read and update.

Key rules on create:

• Name convention — the taxonomy name must start with <vendor name> - (Private) - for permissioned taxonomies. The root node is what traders see in the Audience Targeting tree.
• Visibility — GLOBAL must not be combined with non-empty permissions; RESTRICTED requires at least one permission entity.
• Buyable nodes require both code and retail_cpm. Non-buyable nodes are navigational categories only.
• Wholesale CPM is computed recursively as retail_cpm × (revenue_share_pct / 100). When is_clearing_house is true, an explicit wholesale_cpm on a node is preserved instead.
• Revenue share — revenue_share_pct on the request wins; otherwise the vendor configuration default applies.
• Tree limits — 60,000 nodes maximum; duplicate node codes are rejected.
• use_hash must be true if any node code is not int32-like, and cannot be changed to false afterwards.

Updating a taxonomy — POST /audience_taxonomies/{taxonomy_id}. The body follows the same structure as create.

Updates are also subject to: the taxonomy name must keep its existing prefix, use_hash cannot go true → false, and legacy (non-v3.0) taxonomy IDs are rejected.

The two services store taxonomies independently, so creating in v3.0 does not touch the legacy service — your legacy integration keeps working until you switch, which makes rollback low-risk.

1. Fetch each legacy taxonomy tree in full from the legacy API.
2. Clean the payload — strip the legacy taxonomy_id and all node id fields, remove the deprecated top-level description, and replace audience_vendor_id with vendor_id.
3. Validate locally — buyable nodes have code and retail_cpm; no duplicate codes; ≤ 60,000 nodes; use_hash=true if any code is not int32-like.
4. Create in v3.0 (POST /audience_taxonomies) and record the returned taxonomy and node IDs in a legacy → new ID mapping store.
5. Validate the result against the legacy original: name and hierarchy, permissions, retail CPMs, computed or preserved wholesale CPMs.
6. Switch the integration's reads and writes to the v3.0 endpoints using the new IDs.
7. Confirm with Infillion that all taxonomy traffic has moved.

Also worth noting when porting code:

• The meta response wrapper is gone — parse data directly.
• Writes are synchronous and atomic, so remove any status-polling logic. There is no asynchronous status endpoint.
• There is no CSV format helper — convert CSV to JSON before submitting.
• There is no supernode endpoint — use GET /audience_taxonomies with filters.
• There is no DELETE /grants/{org_id}; grants are removed by POSTing empty permission arrays (a destructive synchronisation — coordinate with Infillion first).

A full migration guide and implementation handbook, including the complete field dictionary, validation rules and endpoint mapping, is available from your Client Success contact.

An external data segment (also known as a data pixel) is the output of a pixel mapping process that results in the creation of a single, permissioned audience segment. In contrast to a permissioned taxonomy, which can be managed via API and contain N segments, an external data segment represents one audience segment and is defined within the Onboard section of the Audiences module in MediaMath Platform.

External data segments are permissioned to specific agencies (MediaMath entity structure): organization > agency > advertiser) so all advertisers within the agency will have access to the external data segment. Prior to getting started, the data provider needs to be added to the agency in MediaMath Platform. To have a data provider added, contact your MediaMath representative.

If the data provider already has the appropriate access, follow these steps to get your external data segments created:

1. Define an audience segment by creating an External Data Segment in the Onboard tab within the MediaMath Platform Audience module.

2. Provide the pixel IDs created in step 1 to your data provider.
3. Data provider will then submit a ticket directly to pixelmapping@mediamath.com, including the following. Include each external data segment mapping in the body of the email (or Support ticket) in the line-separated format below.

Note: Requests to pixelmapping@mediamath.com are handled via an automated process, as long as the formatting below is followed in the subject and body of your email. If the format does not conform, requests will be handled within 1 business day.

External Data Segment Example Request

Subject Line: Data Provider Pixel Mapping Request

Description:

Please map the following

ns:8473,mm:679001

ns:8474,mm:679002

ns:8675,mm:679003

ns = the name space of the first pixel being mapped, refer below or reach out to MediaMath support if the namespace is unknown.

mm = MediaMath Namespace. This will always be "mm" in the mapping request.

XXXXXX = the partner's segment code sent to MediaMath via S2S.

YYYYYY = the MathTag ID ("MT_ID") associated with the MediaMath external data segment pixel created in step one.