Bidders - Category service

Article
02/13/2024

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": {
      ...
    }
  }
}

Share via