# Create Audience Segment Taxonomy

Creates a new audience segment taxonomy with nested hierarchical structure.
Access is scoped to the vendor's owning organization; `visibility=GLOBAL` and `revenue_share_pct` may be set only by global admins.

Endpoint: POST /audience_taxonomies
Version: 3.0.1807
Security: Auth0

## Request fields (application/json):

  - `vendor_id` (integer, required)
    ID of the vendor owning this audience segment taxonomy

  - `visibility` (string)
    Visibility scope of the audience segment
    Enum: "GLOBAL", "RESTRICTED"

  - `use_hash` (boolean)
    Whether to use hashed identifiers for this segment

  - `revenue_share_pct` (number)
    Revenue share percentage for this segment

  - `is_clearing_house` (boolean)
    Whether this segment is managed through a clearing house

  - `permissions` (object)
    Access permissions scoped to specific entities

  - `permissions.organizations` (array)
    Organization IDs granted access

  - `permissions.agencies` (array)
    Agency IDs granted access

  - `permissions.advertisers` (array)
    Advertiser IDs granted access

  - `taxonomy` (object, required)
    Root node of the hierarchical taxonomy tree

  - `taxonomy.name` (string, required)
    Display name of the taxonomy node

  - `taxonomy.description` (string)
    Human-readable description of the taxonomy node

  - `taxonomy.code` (string)
    Vendor-defined segment code identifier

  - `taxonomy.buyable` (boolean)
    Whether this segment can be purchased/targeted

  - `taxonomy.retail_cpm` (number)
    Retail cost per thousand impressions

  - `taxonomy.wholesale_cpm` (number)
    Wholesale cost per thousand impressions

  - `taxonomy.uniques` (integer)
    Estimated number of unique users in this segment

  - `taxonomy.children` (array)
    Nested child taxonomy nodes (supports arbitrary depth)

## Response 201 fields (application/json):

  - `data` (object)

  - `data.taxonomy_id` (integer, required)
    ID of the created audience_taxonomies row

  - `data.audience_vendor_id` (integer, required)
    ID of the audience_vendors row associated with this taxonomy

  - `data.revenue_share_pct` (number)
    Revenue share percentage

  - `data.permissions` (object, required)
    Access permissions scoped to specific entities

  - `data.permissions.organizations` (array, required)

  - `data.permissions.agencies` (array, required)

  - `data.permissions.advertisers` (array, required)

  - `data.taxonomy` (object, required)
    Root node of the created taxonomy tree, with IDs populated

  - `data.taxonomy.id` (integer, required)
    ID of the created audience_segment row

  - `data.taxonomy.name` (string, required)
    Display name of the taxonomy node

  - `data.taxonomy.code` (string)
    Stored segment code (raw or CRC32-hashed depending on use_hash)

  - `data.taxonomy.buyable` (boolean, required)
    Whether this segment can be purchased/targeted

  - `data.taxonomy.retail_cpm` (number)
    Retail cost per thousand impressions

  - `data.taxonomy.wholesale_cpm` (number)
    Wholesale cost per thousand impressions

  - `data.taxonomy.uniques` (integer)
    Estimated number of unique users in this segment

  - `data.taxonomy.children` (array)
    Nested child nodes, mirroring the request tree

  - `meta` (object)

  - `meta.status` (string)

## Response 400 fields (application/json):

  - `errors` (array, required)

  - `errors.code` (string)

  - `errors.sub_code` (string)
    Optional identifier that refines the generic `code` category (e.g. `html5-noscript-tag`). Present on HTML5 upload/preview validation errors; absent otherwise.

  - `errors.field` (string)
    Optional when it is a schema error

  - `errors.message` (string)

  - `meta` (object, required)

  - `meta.status` (string, required)

## Response 403 fields (application/json):

  - `errors` (array, required)

  - `errors.code` (string)

  - `errors.sub_code` (string)
    Optional identifier that refines the generic `code` category (e.g. `html5-noscript-tag`). Present on HTML5 upload/preview validation errors; absent otherwise.

  - `errors.field` (string)
    Optional when it is a schema error

  - `errors.message` (string)

  - `meta` (object, required)

  - `meta.status` (string, required)

## Response 500 fields (application/json):

  - `errors` (array, required)

  - `errors.code` (string)

  - `errors.sub_code` (string)
    Optional identifier that refines the generic `code` category (e.g. `html5-noscript-tag`). Present on HTML5 upload/preview validation errors; absent otherwise.

  - `errors.field` (string)
    Optional when it is a schema error

  - `errors.message` (string)

  - `meta` (object, required)

  - `meta.status` (string, required)