# Permission Taxonomies

_

## Create Permission Taxonomy

 - [POST /audience_segments](https://apidocs.mediamath.com/apis/audience-taxonomies/permission-taxonomies/post_audience_segments.md): 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:
*  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. 
*  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.
*  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



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

### Segment Name
: 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 :
*  represents the taxonomy object in our database and rolls up to your data vendor ID. When updating the taxonomy, reference this ID.
*  represents the individual taxonomy and must be referenced when you want to update the taxonomy.
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.
*  represents the revenue share agreed upon with MediaMath.
*  represents the amount the data vendor will accrue when the segment is inclusion or exclusion targeted within a TerminalOne strategy. 
*  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


## List Permission Taxonomies

 - [GET /audience_segments](https://apidocs.mediamath.com/apis/audience-taxonomies/permission-taxonomies/get_audience_segments.md): 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."

## Get Permission List

 - [GET /audience_segments/grants/{vendor_id}](https://apidocs.mediamath.com/apis/audience-taxonomies/permission-taxonomies/get_audience_segments-grants-$vendor_org_id.md): 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. 


## Get Permission Taxonomy

 - [GET /audience_segments/{taxonomy_id}](https://apidocs.mediamath.com/apis/audience-taxonomies/permission-taxonomies/get_audience_segments-taxonomy_id.md): With a taxonomy ID (obtained by creating a new taxonomy), you can retrieve the taxonomy to review permissions and audience segment details.

## Update Permission Taxonomy

 - [POST /audience_segments/{taxonomy_id}](https://apidocs.mediamath.com/apis/audience-taxonomies/permission-taxonomies/post_audience_segments-taxonomy_id.md): With a taxonomy ID (obtained from creating a new taxonomy), you can update the taxonomy, change permissions, and add or remove audience segments.


 

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