Permission Taxonomies
/
List Permission Taxonomies

Audience Segments API (2.0)

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.

Audience Segments & Taxonomies

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 (Global)

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:

Audience Tab Annotated

Taxonomies (Permissioned)

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.

Revenue Share at Taxonomy Level

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.

Taxonomy Management

Taxonomies are managed using one of two methods:

Taxonomy Format

For data providers not integrated with the API, taxonomies can be managed using a CSV file.

Column NameExample ValueDescriptionType
full_path|Data.com|Age|30-35|Pipe delimited node representation from root (must start with a pipe character)String
code12345Data provider's segment identifier, which should be unique to this segmentInteger
uniques1000000Number of unique users in this segment (rounded estimate)Integer
wholesale_cpm0.80The CPM (Cost per Thousand Impressions) that MediaMath will pay the data provider, in US DollarsDecimal (2dp)
retail_cpm1.10The CPM (Cost per Thousand Impressions) that Buyers will pay MediaMath, in US Dollars. This is the value that is shown to buyers in the MediaMath Platform Audience Targeting TabDecimal (2dp)
buyable1Used to separate segments from non-purchasable categories (which aid navigation in MediaMath Platform). When "1" it will be buyable; when "0" it is not buyable and only requires full_path field to be populated.Integer 1 or 0

Sample Taxonomy

Note: The full_path always starts with a pipe.

full_pathcodeuniqueswholesale_cpmretail_cpmbuyable
|BlueKai0
|BlueKai|Group 10
|BlueKai|Group 1|Segment 10
|BlueKai|Group 1|Segment 20
|BlueKai|Group 1|Segment 3245244661,6640.8511
|BlueKai|Group 1|Segment 42452453,585,1180.8511
|BlueKai|Group 1|Segment 52452465,247,4100.8511
|BlueKai|Group 20
|BlueKai|Group 2|Segment 624524734,3550.8511
|BlueKai|Group 2|Segment 724524813,2480.8511
|BlueKai|Group 2|Segment 82452498,242,5430.8511
|BlueKai|Group 2|Segment 92452509,857,9830.8511
|BlueKai|Group 2|Segment 1024525134,3240.8511

Providing a Taxonomy via CSV

To provide a taxonomy - global or permissioned - for your data in MediaMath Platform:

  1. Following the format above, produce a CSV containing your segments
  2. Validate the CSV file format
  3. Submit the properly formatted CSV, along with your vendor ID (obtained from the partnerships team) to MediaMath Support
  4. If requesting an update to an existing taxonomy, provide the taxonomy ID in your request as well

External Data Segments

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.

MediaMath Platform Data Pixel

  1. Provide the pixel IDs created in step 1 to your data provider.
  2. 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.

Download OpenAPI description
audience-taxonomies.json
audience-taxonomies.yaml
Overview
URL https://apidocs.mediamath.com
developers@mediamath.com developers@mediamath.com
License Apache 2.0
Languages
Servers
Mock server
https://apidocs.mediamath.com/_mock/apis/audience-taxonomies/
https://api.mediamath.com/dmp/v2.0/

Permission Taxonomies

_

Operations

Create Permission Taxonomy

Request

To create a new permission taxonomy, submit a POST with the Content-Type set to "application/json".

The body of the API call will be raw JSON and consists of 3 sections:

  • Permissions: You may provide any number of permissions to allow entities in TerminalOne (organizations, agencies and/or advertisers) access to the taxonomy. These organization, agency, and advertiser IDs can be entered as comma separated values within the ‘permissions’ section of the body. To identify IDs for your customers, reach out to MediaMath Support or ask your customer to locate their IDs within TerminalOne's Admin module.
  • Vendor ID: Every taxonomy rolls up to a MediaMath data vendor entity. The data vendor ID will need to be provided when you create new taxonomies. This ID will be provided to you by the partnerships team.
  • Taxonomy body: This describes the way in which the taxonomy will be shared in TerminalOne. This will be a hierarchical tree structure format (root node > leaf node > leaves).

Example Taxonomy (Permissioned) JSON


{
    "permissions": {
        "organizations": [100048
        ],
        "agencies": [114842,108108
        ],
        "advertisers": [171177,141348,137754
        ]
    },
    "vendor_id": 1234,
    "taxonomy": {
        "name": "VENDOR_NAME - (Private) – Acme Co Taxonomy",
        "children": [
            {
                "code": "1234567",
		"uniques": 100000,
                "retail_cpm": 0,
                "buyable": true,
                "name": "Acme Segment 1",
                "children": [
               ]
            },
            {
                "code": "1234568",
		"uniques": 25000,
                "retail_cpm": 0,
                "buyable": true,
                "name": "Acme Segment 2",
                "children": [
                ]
            }
       ]
    }
}

Segment Codes

NOTE: If you are using a segment code that is not a 32-bit integer, pass an optional parameter use_hash:true as part of the JSON request. Additionally, ensure the user files delivered to the MediaMath server note the declaration HashSegments: 1 to ensure proper processing and handling of the user files and taxonomy.

Segment Name

NOTE: Segment name values should not exceeded 255 characters. If you are using a segment name that does not contain latin alphabetic letters then you can convert the name to an ASCII value and pass the encoded name in the POST request. It will then display in the orginal text in T1. Please make sure the ASCII value is encoded using HTML Entities.

API Response

Upon issuing a POST to create the taxonomy, you'll note the following within the response:

  • audience_vendor_id represents the taxonomy object in our database and rolls up to your data vendor ID. When updating the taxonomy, reference this ID.
  • taxonomy_id represents the individual taxonomy and must be referenced when you want to update the taxonomy.
  • id within the lower levels (branches and leaf) of the taxonomy section, id represents the MediaMath object you have just created. When updating a taxonomy, include id to ensure the objects - non-buyable nodes or individual segments - are processed as updates and not new additions to the taxonomy.
  • revenue_share_pct represents the revenue share agreed upon with MediaMath.
  • wholesale_cpm represents the amount the data vendor will accrue when the segment is inclusion or exclusion targeted within a TerminalOne strategy.
  • visibility will equal "GLOBAL" for all public taxonomies and "RESTRICTED" for all permissioned, or private, taxonomies. Responses for permissioned taxonmies will not include this optional parameter; API responses for global taxonomies will always include the parameter.

Example Taxonomy (Permissioned) Creation Response JSON

{
    "meta": {
        "status": "success"
    },
    "data": {
        "taxonomy": {
            "name": "VENDOR_NAME - (Private) - Acme Co Taxonomy",
            "id": 1678332,
            "children": [
                {
                    "uniques": 25000,
                    "children": [],
                    "name": "Acme Segment 1",
                    "retail_cpm": 0,
                    "id": 1678334,
                    "code": "1234567",
                    "buyable": true,
                    "wholesale_cpm": 0.0
                },
                {
                    "uniques": 100000,
                    "children": [],
                    "name": "Acme Segment 2",
                    "retail_cpm": 0,
                    "id": 1678333,
                    "code": "1234568",
                    "buyable": true,
                    "wholesale_cpm": 0.0
                }
            ]
        },
        "audience_vendor_id": 2468,
        "revenue_share_pct": 0.0,
        "taxonomy_id": 100123
    }
}
Bodyapplication/json

_

permissionsobjectrequired
permissions.​organizationsArray of integers
permissions.​agenciesArray of integers
permissions.​advertisersArray of integers
vendor_idintegerrequired
taxonomyobjectrequired
taxonomy.​namestringrequired

Taxonomy name values should not exceeded 255 characters.

taxonomy.​childrenArray of objectsrequired
taxonomy.​children[].​namestringrequired

Segment name values should not exceeded 255 characters.

taxonomy.​children[].​buyablebooleanrequired
taxonomy.​children[].​childrenArray of objects
string
use_hashboolean

If you are using a segment code that is not a 32-bit integer, pass an optional parameter use_hash:true as part of the JSON body.

curl -i -X POST \
  https://apidocs.mediamath.com/_mock/apis/audience-taxonomies/audience_segments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "permissions": {
      "organizations": [
        0
      ],
      "agencies": [
        0
      ],
      "advertisers": [
        0
      ]
    },
    "vendor_id": 0,
    "taxonomy": {
      "name": "string",
      "children": [
        {
          "name": "string",
          "buyable": true,
          "children": [
            {
              "uniques": 0,
              "children": [
                {}
              ],
              "name": "string",
              "retail_cpm": 0,
              "code": "string",
              "buyable": true
            }
          ]
        }
      ],
      "": "string"
    },
    "use_hash": true
  }'

Responses

Bodyapplication/json
metaobject
dataobject
Response
application/json
{
  "meta": {
    "status": "success"
  },
  "data": {
    "permissions": { … },
    "created_on": "timestamp",
    "updated_on": "timestamp",
    "taxonomy": { … },
    "vendor_id": 1234,
    "taxonomy_id": 127001
  }
}

List Permission Taxonomies

Request

Query parameters should be of the form (field)(operator)(value) where operator can be == (equal to) or =: (like)

Example: /?q=name=:MediaMath will return segments within your taxonomies that have names like "MediaMath."

Query
qstring

Query String Parameter

name==[name]

buyable==[boolean]

Headers
Content-Typestringrequired

Content-Type

Cookiestringrequired

Cookie

curl -i -X GET \
  'https://apidocs.mediamath.com/_mock/apis/audience-taxonomies/audience_segments?q=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: string' \
  -H 'Cookie: string'

Responses

Bodyapplication/json
dataArray of objects
metaobject
Response
application/json
{
  "data": [
    { … },
    { … },
    { … }
  ],
  "meta": {
    "status": "success",
    "total_count": 3
  }
}

Get Permission List

Request

This will retrieve entity IDs in the MediaMath Platform (organizations, agencies and/or advertisers) to which you, as a data provider, have access. To identify entity IDs for your customers and request your grants be updated, reach out to MediaMath Support or ask your client to locate their relevants IDs within the MediaMath Platform Admin section.

Path
vendor_idstringrequired

Your vendor ID, provided by MediaMath partnerships team.

curl -i -X GET \
  'https://apidocs.mediamath.com/_mock/apis/audience-taxonomies/audience_segments/grants/{vendor_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json
metaobject
dataobject
Response
application/json
{
  "meta": {
    "status": "success"
  },
  "data": {
    "organizations": [ … ],
    "agencies": [ … ],
    "advertisers": [ … ]
  }
}

Get Permission Taxonomy

Request

With a taxonomy ID (obtained by creating a new taxonomy), you can retrieve the taxonomy to review permissions and audience segment details.

Path
taxonomy_idstringrequired

taxonomy_id

curl -i -X GET \
  'https://apidocs.mediamath.com/_mock/apis/audience-taxonomies/audience_segments/{taxonomy_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json
dataobject
metaobject
Response
application/json
{
  "meta": {
    "status": "success"
  },
  "data": {
    "permissions": { … },
    "created_on": "2018-04-03T15:45:07Z",
    "updated_on": "2018-04-03T15:45:07Z",
    "taxonomy": { … },
    "audience_vendor_id": 123,
    "taxonomy_id": 123,
    "revenue_share_pct": 50
  }
}

Update Permission Taxonomy

Request

With a taxonomy ID (obtained from creating a new taxonomy), you can update the taxonomy, change permissions, and add or remove audience segments.

NOTE: you must always post the entire taxonomy when updating a taxonomy.

To ensure that the entire taxonomy is correct, we recommend updates be done as a 3-step process:

  1. GET the existing taxonomy (see example API response with definitions)
  2. Identify & make changes (i.e. add/edit permissions, add/remove leaf nodes, change retail CPMs, etc)
  3. POST the updated taxonomy
Path
taxonomy_idstringrequired

taxonomy_id

Headers
Content-Typestringrequired

_

Bodyapplication/json

_

audience_vendor_idintegerrequired
permissionsobject
taxonomyobjectrequired
taxonomy.​childrenArray of objectsrequired
taxonomy.​children[].​buyableboolean
taxonomy.​children[].​childrenArray of objects
taxonomy.​children[].​idinteger
taxonomy.​children[].​namestring
taxonomy.​descriptionstring
taxonomy.​idinteger
use_hashboolean

If you are using a segment code that is not a 32-bit integer, you'd have to pass an optional parameter use_hash:true as part of the JSON body.

Default false
curl -i -X POST \
  'https://apidocs.mediamath.com/_mock/apis/audience-taxonomies/audience_segments/{taxonomy_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "audience_vendor_id": 0,
    "permissions": {
      "advertisers": [
        0
      ],
      "agencies": [
        0
      ],
      "organizations": [
        0
      ]
    },
    "taxonomy": {
      "children": [
        {
          "buyable": true,
          "children": [
            {
              "buyable": true,
              "children": [
                {}
              ],
              "code": 0,
              "id": 0,
              "name": "string",
              "retail_cpm": 0,
              "uniques": 0,
              "wholesale_cpm": 0
            }
          ],
          "id": 0,
          "name": "string"
        }
      ],
      "description": "string",
      "id": 0
    },
    "use_hash": false
  }'

Responses

Bodyapplication/json
dataobject
metaobject
Response
application/json
{
  "data": {
    "audience_vendor_id": 470,
    "created_by": null,
    "created_on": "2017-03-22T19:36:05Z",
    "permissions": { … },
    "revenue_share_pct": 0,
    "taxonomy": { … },
    "taxonomy_id": 100001,
    "updated_by": 14571,
    "updated_on": "2018-06-15T14:55:51Z",
    "visibility": "RESTRICTED"
  },
  "meta": {
    "status": "success"
  }
}