post

/audience_segments

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.

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 global taxonomies and “RESTRICTED” for all permissioned 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
    }
}

Authorization

oauth2 - password

Request Body

Schema
object
permissions
object
required
vendor_id
integer
required
taxonomy
object
required
use_hash
boolean

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.

Responses

1 Example
Schema
object
meta
object
data
object

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
oauth_access_token