{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Taxonomy Management","description":"MediaMath comprehensive APIs empower users to programmatically access and modify campaigns, reports, and log data in MediaMath Platform."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"taxonomy-management","__idx":0},"children":["Taxonomy Management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using the Audience Segments API, customers and data providers have control to onboard and activate the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"http://www.mediamath.com/legal/terms/audiencedata_policy/"},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"audience-segments--taxonomies","__idx":1},"children":["Audience Segments & Taxonomies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ways to expose the data onboarded via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/server-to-server"},"children":["server-to-server"]}," within MediaMath Platform:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Taxonomies"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["These can be global, meaning all MediaMath customers will have access to the segments within the taxonomy in MediaMath Platform."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["These can be permissioned so that only select MediaMath customers have access to the segments within the taxonomy in MediaMath Platform."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["External Data Segments"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["These represent a single segment and are always permissioned."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["These are also referred to as Data Pixels."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note: The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/server-to-server"},"children":["S2S data transfer"]}," is the same for both global and permissioned taxonomies, as well as external data segments."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"taxonomies-global","__idx":2},"children":["Taxonomies (Global)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this view, the Audience Targeting view has been annotated to show the elements of a taxonomy:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://mediamath.github.io/api-docs/images/audience_tab.png","alt":"Audience Tab Annotated"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"taxonomies-permissioned","__idx":3},"children":["Taxonomies (Permissioned)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"revenue-share-at-taxonomy-level","__idx":4},"children":["Revenue Share at Taxonomy Level"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To override a revenue share at the taxonomy level, create the taxonomy with permissions and contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://mediamathsupport.force.com/s/"},"children":["MediaMath Support"]}," with the following information:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the Taxonomy_ID,"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the desired taxonomy-level revenue share."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Our team will respond once they have updated the revenue share for the specified taxonomy."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"taxonomy-management-1","__idx":5},"children":["Taxonomy Management"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"The legacy Audience Segments taxonomy API is deprecated"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The legacy Audience Segment Service (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/dmp/v2.0/audience_segments/..."]},") has been ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["deprecated since 1st August 2026"]}," and will be retired. Taxonomy management now lives in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Campaigns API v3.0"]},", which is a new, more performant service with the same underlying concepts — vendor configuration, grants and taxonomy trees — under new paths."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full endpoint reference: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://apidocs.mediamath.com/apis/campaigns-api/openapi"},"children":["https://apidocs.mediamath.com/apis/campaigns-api/openapi"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All new integrations must build against v3.0. Existing integrations should migrate using the guidance below."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"whats-changed","__idx":6},"children":["What's changed"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Area"},"children":["Area"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Legacy (Audience Segment Service)"},"children":["Legacy (Audience Segment Service)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Campaigns API v3.0"},"children":["Campaigns API v3.0"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Base URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/dmp/v2.0/"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v3.0/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bearer token or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bearer token only"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Grants lookup"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["By ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendor_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["By ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["org_id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Taxonomy endpoint"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/audience_segments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/audience_taxonomies"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Taxonomy & node IDs"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Legacy IDs"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["New IDs, generated at recreation"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Write processing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Asynchronous (HTTP 202)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Synchronous & atomic (HTTP 200)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Response wrapper"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," only"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Two breaking changes to plan for"},"children":[{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionid"]}," is not accepted."]}," Bearer token is the only supported authentication scheme, and grant operations key off the owning organisation ID rather than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendor_id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["IDs are not shared between the two services."]}," Taxonomies are ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["recreated"]}," in v3.0 and receive new taxonomy and node IDs. This is a planned, one-time change — your integration must capture and store the new IDs."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"authentication-and-base-url","__idx":7},"children":["Authentication and base URL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All v3.0 endpoints require a Bearer token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header, obtained through the standard MediaMath OAuth flow — see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication guide"]}," for how to obtain and refresh one. Endpoint paths below are relative to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.mediamath.com/api/v3.0/"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"curl --location 'https://api.mediamath.com/api/v3.0/<endpoint>' \\\n   --header 'Authorization: Bearer <token>' \\\n   --header 'Content-Type: application/json'\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"the-new-endpoints","__idx":8},"children":["The new endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Taxonomies"]}," — these are the endpoints your integration will spend most of its time in. Full schemas are in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://apidocs.mediamath.com/apis/campaigns-api/openapi"},"children":["Campaigns API v3.0 reference"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List taxonomies"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /audience_taxonomies"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paginated. Supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["q"]}," (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["q=visibility==RESTRICTED"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_by"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_limit"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_offset"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get one taxonomy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /audience_taxonomies/{taxonomy_id}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Returns the full tree. Use this as the authoritative read before building an update payload. Legacy IDs are not valid here."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a taxonomy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /audience_taxonomies"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Creates the tree with visibility, permissions and pricing. Returns the generated taxonomy and node IDs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update a taxonomy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /audience_taxonomies/{taxonomy_id}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same body structure as create, but existing nodes ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," be sent with their current ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Look up segments for targeting"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /path_audiences_segments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unchanged endpoint; the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legacy"]}," query parameter selects which segment set is read."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Who calls it"},"children":["Who calls it"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read grants for your organisation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /grants/{org_id}?with=entity_info"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client integrations (read-only)"]}," and global admins"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List / write grants"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /grants"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /grants/{org_id}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Global admins only"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Vendor audience configs"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /vendor/audience_configs"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /vendor/{vendor_id}/audience_configs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Global admins only"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"path_audiences_segments and the legacy flag"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /path_audiences_segments"]}," takes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legacy"]}," boolean. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legacy=false"]}," reads v3.0 segments; omitting the parameter or passing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legacy=true"]}," reads DMP segments. The current default is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legacy=true"]},", so existing integrations are unaffected — but the default will switch to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legacy=false"]}," as migration progresses, so pass the parameter explicitly. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["q"]}," is required; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["advertiser_id"]}," is required for private/custom taxonomy lookups."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"how-to-use-them","__idx":9},"children":["How to use them"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every taxonomy create or update passes three checks before processing:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Vendor audience config"]}," — does ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendor_id"]}," have a configuration? This defines the owning organisation, bidder code, default revenue share and creation limit. ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(Managed by Infillion.)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Organisation grants"]}," — are grants configured for the owning organisation? These define which organisations, agencies and advertisers you may permission a taxonomy to. ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(Managed by Infillion.)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request permissions"]}," — is everything in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions"]}," block inside that grant scope, and are the visibility rules satisfied? ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(Entirely client-controlled.)"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Before your first create"]},", read your grants with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /grants/{org_id}?with=entity_info"]}," and treat them as the outer boundary for every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions"]}," block you send. Requesting a subset of the grant scope always passes; anything outside it always fails."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Creating a taxonomy"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /audience_taxonomies"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"curl --location 'https://api.mediamath.com/api/v3.0/audience_taxonomies' \\\n   --request POST \\\n   --header 'Authorization: Bearer <token>' \\\n   --header 'Content-Type: application/json' \\\n   --data '{\n     \"vendor_id\":   1024,\n     \"visibility\":  \"RESTRICTED\",\n     \"use_hash\":    true,\n     \"permissions\": {\n       \"organizations\": [2001],\n       \"agencies\":      [3101],\n       \"advertisers\":   [45001]\n     },\n     \"taxonomy\": {\n       \"name\":     \"Acme Data - (Private) - Interest Taxonomy\",\n       \"buyable\":  false,\n       \"children\": [\n         { \"name\": \"Sports\", \"code\": \"sports_root\",\n           \"buyable\": true, \"retail_cpm\": 2.5, \"children\": [] },\n         { \"name\": \"Travel\", \"code\": \"travel_root\",\n           \"buyable\": true, \"retail_cpm\": 3.2, \"children\": [] }\n       ]\n     }\n   }'\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response is an HTTP 200 with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," object containing the created taxonomy, its generated taxonomy and node IDs, the applied ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["revenue_share_pct"]},", visibility and vendor information. Unlike the legacy DMP API, which returned a temporary ID before the segment had synced, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key rules on create:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Name convention"]}," — the taxonomy name must start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<vendor name> - (Private) - "]}," for permissioned taxonomies. The root node is what traders see in the Audience Targeting tree."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Visibility"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GLOBAL"]}," must not be combined with non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESTRICTED"]}," requires at least one permission entity."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Buyable nodes"]}," require both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retail_cpm"]},". Non-buyable nodes are navigational categories only."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Wholesale CPM"]}," is computed recursively as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retail_cpm × (revenue_share_pct / 100)"]},". When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_clearing_house"]}," is true, an explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wholesale_cpm"]}," on a node is preserved instead."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Revenue share"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["revenue_share_pct"]}," on the request wins; otherwise the vendor configuration default applies."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tree limits"]}," — 60,000 nodes maximum; duplicate node codes are rejected."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use_hash"]}]}," must be true if any node code is not int32-like, and cannot be changed to false afterwards."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Updating a taxonomy"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /audience_taxonomies/{taxonomy_id}"]},". The body follows the same structure as create."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Carry existing node IDs — the single most important rule"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On update, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["existing nodes must be sent with their current ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},". A node sent with its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," is amended in place and live Strategies targeting it are unaffected. A node sent ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["without"]}," an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," is created as a brand new node with a new ID — the previous node is retired to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retired_audience_segments"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retired_strategy_audience_segments"]},", and Strategies still pointing at the old ID stop delivering once users age out of the segment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always read the current tree with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /audience_taxonomies/{taxonomy_id}"]}," and build your update payload from it. Never rebuild an update from a partial lookup."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Updates are also subject to: the taxonomy name must keep its existing prefix, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use_hash"]}," cannot go true → false, and legacy (non-v3.0) taxonomy IDs are rejected."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"migrating-an-existing-taxonomy","__idx":10},"children":["Migrating an existing taxonomy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fetch"]}," each legacy taxonomy tree in full from the legacy API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Clean the payload"]}," — strip the legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["taxonomy_id"]}," and all node ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," fields, remove the deprecated top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]},", and replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience_vendor_id"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendor_id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validate locally"]}," — buyable nodes have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retail_cpm"]},"; no duplicate codes; ≤ 60,000 nodes; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use_hash=true"]}," if any code is not int32-like."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create in v3.0"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /audience_taxonomies"]},") and record the returned taxonomy and node IDs in a legacy → new ID mapping store."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validate the result"]}," against the legacy original: name and hierarchy, permissions, retail CPMs, computed or preserved wholesale CPMs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Switch"]}," the integration's reads and writes to the v3.0 endpoints using the new IDs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Confirm with Infillion"]}," that all taxonomy traffic has moved."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Also worth noting when porting code:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}," response wrapper is gone — parse ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," directly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Writes are synchronous and atomic, so remove any status-polling logic. There is no asynchronous status endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["There is no CSV format helper — convert CSV to JSON before submitting."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["There is no supernode endpoint — use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /audience_taxonomies"]}," with filters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["There is no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /grants/{org_id}"]},"; grants are removed by POSTing empty permission arrays (a destructive synchronisation — coordinate with Infillion first)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"common-errors","__idx":11},"children":["Common errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Resolution"},"children":["Resolution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vendor_id does not have an audience configuration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No vendor audience configuration exists"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact Infillion to provision it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["taxonomy vendor/organization has no grants configured"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The owning organisation has no grants"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact Infillion to configure grants"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["No permission to create/update taxonomy on the following resources…"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requested permissions exceed grant scope"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reduce the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions"]}," block to entities within scope, or request a grant change"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["visibility GLOBAL is incompatible with permissions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GLOBAL"]}," sent with a non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions"]}," block"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Remove the permissions block, or use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESTRICTED"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["when visibility is RESTRICTED, at least one permission entity must be set"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RESTRICTED"]}," sent with an empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions"]}," block"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provide at least one organisation, agency or advertiser"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication failure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing/invalid Bearer token, or legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionid"]}," used"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use Bearer token authentication only — see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication guide"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Missing segments"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Incomplete pagination is the most common cause of a \"missing\" segment. Iterate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_offset"]}," until a page returns fewer results than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_limit"]}," before concluding a taxonomy or node is absent — and never delete and recreate a segment in response to a failed lookup, as recreation generates a new ID and disconnects any Strategies targeting the original. If an entity is genuinely absent after a complete read, contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://mediamathsupport.force.com/s/"},"children":["MediaMath Support"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A full migration guide and implementation handbook, including the complete field dictionary, validation rules and endpoint mapping, is available from your Client Success contact."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"external-data-segments","__idx":12},"children":["External Data Segments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the data provider already has the appropriate access, follow these steps to get your external data segments created:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Define an audience segment by creating an External Data Segment in the Onboard tab within the MediaMath Platform Audience module."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://mediamath.github.io/api-docs/images/t1_data_pixel_form.png","alt":"MediaMath Platform Data Pixel"},"children":[]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Provide the pixel IDs created in step 1 to your data provider."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Data provider will then submit a ticket directly to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Requests to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["External Data Segment Example Request"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Subject Line: Data Provider Pixel Mapping Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Description:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please map the following"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ns:8473,mm:679001"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ns:8474,mm:679002"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ns:8675,mm:679003"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ns = the name space of the first pixel being mapped, refer below or reach out to MediaMath support if the namespace is unknown."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["mm = MediaMath Namespace. This will always be \"mm\" in the mapping request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["XXXXXX = the partner's segment code sent to MediaMath via S2S."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["YYYYYY = the MathTag ID (\"MT_ID\") associated with the MediaMath external data segment pixel created in step one."]}]},"headings":[{"value":"Taxonomy Management","id":"taxonomy-management","depth":1},{"value":"Audience Segments & Taxonomies","id":"audience-segments--taxonomies","depth":2},{"value":"Taxonomies (Global)","id":"taxonomies-global","depth":3},{"value":"Taxonomies (Permissioned)","id":"taxonomies-permissioned","depth":3},{"value":"Revenue Share at Taxonomy Level","id":"revenue-share-at-taxonomy-level","depth":4},{"value":"Taxonomy Management","id":"taxonomy-management-1","depth":3},{"value":"What's changed","id":"whats-changed","depth":4},{"value":"Authentication and base URL","id":"authentication-and-base-url","depth":4},{"value":"The new endpoints","id":"the-new-endpoints","depth":4},{"value":"How to use them","id":"how-to-use-them","depth":4},{"value":"Migrating an existing taxonomy","id":"migrating-an-existing-taxonomy","depth":4},{"value":"Common errors","id":"common-errors","depth":4},{"value":"External Data Segments","id":"external-data-segments","depth":3}],"frontmatter":{"seo":{"title":"Taxonomy Management"}},"lastModified":"2026-09-22T17:24:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/taxonomy-management","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}