List Management API

The List Management API allows the ability to control what types of ads are displayed in a specified app. By default, all apps will use the IAB Content Taxonomy 1.0 list.

Before You Get Started πŸ”—

Endpoints πŸ”—

Endpoint Description
GET /v4/lists Get all lists of IAB categories in your account. User can also get a specific IAB category list, identified using an unique ID.
GET /v4/lists/{list_id} Get the existing list of a company by provided ID.
POST /v4/lists CREATE a new IAB category list and apply it to an app.
PUT /v4/lists/{list_id} Update a given IAB category list to either add or delete IAB categories to said list, identifying list via ID.
DELETE /v4/lists/{list_id} DELETE a given IAB category list, identifying list via ID.

Get a list of IAB Categories πŸ”—

GET /v4/lists

Retrieves all the available lists with pagination and filtering.

Required Headers πŸ”—

Authorization: {X-Chartboost-Company-ID, X-Chartboost-User-ID}
Content-Type: application/json;charset=UTF-8

Optional Parameters πŸ”—

Parameter Type Valid Values Description
keyword_filter string (any string) Used as search key word.
types_filter string (all the possible list types) Filter parameter to only get lists of the specified list type
limit int Any number greater than 1 Amount of items per page. Default: 25
page int Any number greater than 1 Requested page number.
sort string Available sort fields: title, date_modified, date_created Sort criteria based on the fields.
direction string ASC or DESC Default: ASC. Sort direction for the sorting criteria. ASC = Ascending, DESC = Decending
summary boolean true or false Default: false. If true, a short response is provided. If false, a long response is provided.

Request Example πŸ”—

GET /lists
Host: api.chartboost.com
Authorization: {X-Chartboost-Company-ID, X-Chartboost-User-ID}
Content-Type: application/json;charset=UTF-8

Responses πŸ”—

  • 200 - OK Successful Response
  • 400 - Bad Resquest Response

Summary (False) Long Response Example πŸ”—

{
  "items": [
    {
      "id": <string>, // ID of the list
      "title": <string>, // the title of the list
      "type": <string>, // the list type, from a predefined enum of available types
      "date_created": <timestamp>, // date when the list was created
      "date_modified": <timestamp>, // last date when the list was modified
      "elements": [
           // list of elements, the format depends on the "type" field
           // It includes default list
    // (ex: "IAB1-1")
 
      ],
    },
    {
  "id": <string>,
  "title": "Sensitive IAB Taxonomy content v1.0 Chartboost default blocked categories",
  "type": "iab_content_taxonomy_1.0_chartboost_default",
  "date_created": <timestamp>,
  "date_modified": <timestamp>,
  "elements": [
    {
      // the list elements
    }
  ]
    }
    ...
    ],
    page: <integer>, // current page
    limit: <integer>, // current limit
    total: <integer> // total available items
}

Summary (True) Short Response Example πŸ”—

{
  "items": [
    {
      "id": <string>, // ID of the list
      "title": <string>, // the title of the list
      "type": <string>, // the list type, from a predefined enum of available types
      "date_created": <timestamp>, // date when the list was created
      "date_modified": <timestamp>, // last date when the list was modified
      "total_elements": <int> // total elements in the list
    },
    ...
    ],
    page: <integer>, // current page
    limit: <integer>, // current limit
    total: <integer> // total available items
}


Get an existing list by ID πŸ”—

GET /v4/lists/{list_id}

Retrieves the current list by provided ID.

Required Headers πŸ”—

Authorization: {X-Chartboost-Company-ID, X-Chartboost-User-ID}
Content-Type: application/json;charset=UTF-8

Parameters πŸ”—

Field Type Description
id string ID of the list.

Response Example πŸ”—

{
  "id": <string>, // ID of the list
  "title": <string>, // the title of the list
  "type": <string>, // the list type, from a predefined enum of available types
  "date_created": <timestamp>, // date when the list was created
  "date_modified": <timestamp>, // last date when the list was modified
  "elements": [
    {
      // list of elements, the format depends on the "type" field
    },
    ...
  ]
}

Responses πŸ”—

  • 200 - OK Successful Response
  • 404 - Validation Error Response

Create a new list πŸ”—

POST /v4/lists

Creates a new list by passing the title, type and list of elements.

Required Headers πŸ”—

Authorization: {X-Chartboost-Company-ID, X-Chartboost-User-ID}
Content-Type: application/json;charset=UTF-8

Parameters πŸ”—

Field Type Description
title string The title of the list.
type string The list type from a pre-defined enum of available types.
elements Β  List of elements. Refer to IAB Content Taxonomy 1.0. Tier 1 categories cannot be passed (e.g. IAB1, IAB12). Only Tier 2 categories, or sub-categories, can be passed (e.g. IAB1-1, IAB12-3).

Request Example πŸ”—

{
  "title": <string>, // the title of the list
  "type": <string>, // the list type, from a predefined enum of available types
  "elements": [
    {
      // list of elements, the format depends on the "type" field
      // default list will not be sent through the body
    },
    ...
  ]
}

Responses πŸ”—

  • 200 - OK Successful Response
  • 400 - Bad Resquest Response

200 OK Successful Response Example

{
  "id": <string> // ID of the new list
}

Update an existing list by ID πŸ”—

PUT /v4/lists/{list_id}

Updates an existing list by provided ID.

Required Headers πŸ”—

Authorization: {X-Chartboost-Company-ID, X-Chartboost-User-ID}
Content-Type: application/json;charset=UTF-8

Request Example πŸ”—

{
  "title": <string>, // the title of the list
  "type": <string>, // the list type, from a predefined enum of available types
  "elements": [
    {
      // list of elements, the format depends on the "type" field
    },
    ...
  ]
}

Parameters πŸ”—

Field Type Description
title string The title of the list.
type string The list type from a pre-defined enum of available types.
elements Β  List of elements. Refer to IAB Content Taxonomy 1.0. Tier 1 categories cannot be passed (e.g. IAB1, IAB12). Only Tier 2 categories, or sub-categories, can be passed (e.g. IAB1-1, IAB12-3).

Responses πŸ”—

  • 200 - OK Successful Response
  • 400 - Bad Resquest Response

200 OK Successful Response Example

{
  "id": <string>, // ID of the list
  "title": <string>, // the title of the list
  "type": <string>, // the list type, from a predefined enum of available types
  "elements": [
    {
      // list of elements, the format depends on the "type" field
    },
    ...
  ]
}

Delete an existing list by ID πŸ”—

DELETE /v4/lists/{list_id}

Deletes an existing list by provided ID.

Required Headers πŸ”—

Authorization: {X-Chartboost-Company-ID, X-Chartboost-User-ID}
Content-Type: application/json;charset=UTF-8

Responses πŸ”—

  • 204 - No Content Response
  • 404 - Validation Error Response