Bidders - Category service

The read-only Category Service allows you to view all categories that are registered in the Xandr system. Categories are assigned to both brands and creatives - you can see what categories are assigned using the Brand Service or the Creative Service. You can then allow or disallow these categories of brands and creatives using the Ad Profile Service.

Note

For site and placement categories, use the Content Category Service.

REST API

HTTP Method	Endpoint	Description
GET	https://api.adnxs.com/category	View all the categories in the Xandr system.
GET	https://api.adnxs.com/category/CATEGORY_ID	View information about a particular category.

JSON fields

Note

The fields countries_and_brands and countries_and_regions defined below are being used by our system to allow gambling-related creatives to serve in the countries and regions where they're legally allowed, putting us in compliance with applicable laws.

• For more information about our official gambling-related policies, see our buy-side and sell-side gambling policies.
• For more information on how allowlisting works by country and region, contact Customer Support.

Field	Type	Description
id	int	The ID of the category. Required On: PUT, in query string
name	string	The name of the category. Required On: POST
is_sensitive	boolean	If true, the category is listed as "sensitive", and is often banned by publishers. Default: false
last_modified	timestamp	The date and time when the category was last modified.
requires_allowlist_on_external	boolean	Whether brands or creatives in this category require allowlisting in order to serve on external (i.e. RTB) inventory. Default: false
requires_allowlist_on_managed	boolean	Whether brands or creatives in this category require allowlisting in order to serve on managed inventory. Default: false
is_brand_eligible	boolean	If true, then the category is eligible to be associated with brands within the audit process. Default: true
requires_allowlist	boolean	Whether brands or creatives in this category require allowlisting in order to serve. Default: false
countries_and_brands	array of objects	This array contains brand allowlist settings grouped by country. For more information, see "Countries and Brands" below.

Countries and brands

Field	Type	Description
brand_id	int	The ID of the brand.
brand_name	string	The name of the brand.
brand	multi_object	An object containing information about the brand allowlisted in this country. For more information, see "Brand" below.
country	string	A 2-character string referencing the country in which the brand is allowlisted. For a list of supported codes, refer the ISO 3166-1 country codes.

Regions and brands

Field	Type	Description
brand_id	int	The ID of the brand.
brand_name	string	The name of the brand.
brand	multi_object	An object containing information about the brand allowlisted in this region.
region	string	A string referencing the region in which the brand is allowlisted. For a list of supported codes, see the ISO 3166-2.

Examples

View all categories

$ curl -b cookies -c cookies "https://api.adnxs.com/category"
{
  "response": {
    "status": "OK",
    "count": 88,
    "start_element": null,
    "num_elements": null,
    "categories": [
      {
        "id": 1,
        "name": "Airlines",
        "is_sensitive": false,
        "last_modified": "2010-03-19 17:48:36",
        "requires_allowlist_on_external": false,
        "requires_allowlist_on_managed": false,
        "is_brand_eligible": true,
        "requires_allowlist": false,
        "allowlist": {
          "countries_and_brands": [],
          "regions_and_brands": []
        }
      },
      {
        "id": 2,
        "name": "Apparel",
        "is_sensitive": false,
        "last_modified": "2010-03-19 17:48:36",
        "requires_allowlist_on_external": false,
        "requires_allowlist_on_managed": false,
        "is_brand_eligible": true,
        "requires_allowlist": false,
        "allowlist": {
          "countries_and_brands": [],
          "regions_and_brands": []
        }
      },
      {
        "id": 3,
        "name": "Appliances",
        "is_sensitive": false,
        "last_modified": "2010-03-19 17:48:36",
        "requires_allowlist_on_external": false,
        "requires_allowlist_on_managed": false,
        "is_brand_eligible": true,
        "requires_allowlist": false,
        "allowlist": {
          "countries_and_brands": [],
          "regions_and_brands": []
        }
      },
      "dbg": {
      ...
    }
  }
}

View a specific category

$ curl -b cookies -c cookies "https://api.adnxs.com/category/1"
{
  "response": {
    "status": "OK",
    "count": 1,
    "start_element": null,
    "num_elements": null,
    "category": {
      "id": 1,
      "name": "Airlines",
      "is_sensitive": false,
      "last_modified": "2010-03-19 17:48:36",
      "requires_allowlist_on_external": false,
      "requires_allowlist_on_managed": false,
      "is_brand_eligible": true,
      "requires_allowlist": false,
      "allowlist": {
        "countries_and_brands": [],
        "regions_and_brands": []
      }
    },
    "dbg": {
      ...
    }
  }
}