# Update Audience Segment Taxonomy

Updates metadata and replaces the taxonomy tree for an existing audience segment taxonomy.
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/{taxonomy_id}
Version: 3.0.1807
Security: Auth0

## Security:

  - `Auth0` (unknown)
    oauth2 scopes: offline_access, manage:services

## Path parameters:

  - `taxonomy_id` (integer, required)
    Numeric ID of the taxonomy to update

## Request fields (application/json):

  - `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, required)
    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 (replaces existing tree)

  - `taxonomy.id` (integer)
    ID of the existing audience_segments row. Omit for new nodes.

  - `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 200:

  - `200` (unknown)
    Audience segment taxonomy updated successfully

## Response 200 fields (application/json):

  - `data` (object)

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

  - `data.created_by` (integer, required)
    ID of the user who created the taxonomy (audience_taxonomies.created_by)

  - `data.updated_by` (integer, required)
    ID of the user who last updated the taxonomy (audience_taxonomies.updated_by)

  - `data.created_on` (string, required)
    Timestamp when the taxonomy was created (audience_taxonomies.created_on)

  - `data.updated_on` (string, required)
    Timestamp when the taxonomy was last updated (audience_taxonomies.updated_on)

  - `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)
    Entity-scoped access permissions

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

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

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

  - `data.taxonomy` (object, required)
    Root node of the updated segment 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, required)
    Example: success

## Response 400:

  - `400` (unknown)
    Error response

## 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:

  - `403` (unknown)
    Error response

## 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 404:

  - `404` (unknown)
    Error response

## Response 404 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 409:

  - `409` (unknown)
    Error response

## Response 409 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:

  - `500` (unknown)
    Error response

## 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)