Audience Segments API

  • Version: 2.0
  • Host: api.mediamath.com/dmp/v2.0
  • Protocols: https
  • Accepts: application/json
  • Responds With: application/json

Audience Segments

Permission Taxonomies

Permissioned taxonomies are hierarchical trees that structure 1st and 3rd party segments, for exposure in the T1 Strategy > Targeting > Audience tab. These segments are ‘permissioned’ or exposed to specified organizations, agencies and/or advertisers. To create a new permissioned taxonomy, send an email to support@mediamath.com with the following information:

  1. Organization, agency and advertiser ids that you’d like to permission taxonomies to.
  2. Default agreed upon revenue share

Our partnerships team will respond back to you once they’ve completed the initial setup. You’ll then be able to create and update taxonomies and assign permissions to them.

Revenue Share Override at the Taxonomy Level

Each vendor will be set up with a mutually agreed upon, default revenue share. However, the default share can be overridden at the taxonomy level. For example, if a client wants to expose the segments that were created using a 3rd party DMP for targeting within T1 and are using their vendor’s platform to onboard and expose that data via a taxonomy, the vendor can create the taxonomy using the APIs listed above.

Once the taxonomy is created and the taxonomy_id is assigned, please send an email to support@mediamath.com with the following information:

  • Taxonomy_ID
  • Desired Revenue Share percent

Our partnerships team will update the revenue share percent for the taxonomy and respond back to you.

Taxonomy Service

Note: All requests should use “Content-Type: application/json” and all responses return json.

Creating a new permission taxonomy

To create a new custom taxonomy, you must make a POST with the Content-Type set to “application/json” and include the session_id as the header parameters in the API call

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

  1. Permissions: You may provide any number of permissions to allow individual organizations, agencies and/or advertisers to have access to the new taxonomy. These organization, agency or advertiser ids can be entered as comma separated values within the ‘permissions’ section of the raw body
  2. Vendor ID: Every taxonomy rolls up to a data vendor for billing purposes. You’ll need to provide the vendor_id assigned to you by the partnerships team under this section
  3. Taxonomy body: You’ll provide the taxonomy the way you want it to show up in the T1 UI in a hierarchical tree structure format (root node, leaf node, leaves).
  • The “Taxonomy-ID” from the response above may then be used to make changes to the new custom taxonomy.
  • The revenue_share_pct from the response body is the value that you agreed upon with Mediamath
  • The wholesale_cpm from the response body is the amount that you’ll get paid every time the segment is targeted in a campaign

Updating an existing custom taxonomy

With a Taxonomy-ID in hand (obtained from creating a new taxonomy above), you may now update the taxonomy, change permissions and add/remove audience segments.

Note that you must always post the entire permissions/taxonomy that you want to change when updating a taxonomy. To ensure that the entire permissions/taxonomy is correct, update can be done as a 2-step process:

  1. GET the existing permission taxonomy
  2. Update the taxonomy

Get existing taxonomy: You must make a GET call with the Content-Type set to “application/json” and include the session_id as the header parameter in the API call.

Update existing taxonomy: Use the response body from the GET call above as the JSON body for the POST call. Ensure you remove the following from the response of the GET call

  {
  "meta":{
    "status": "success"
  },
  "data":

You can now add/edit permissions from the permission section and/or add/remove leaf nodes from the taxonomy and/or change the retail CPM values.