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 πŸ”—

Before you get started, complete the API Access & Authentication process.

You will not be able to create or manage your ad locations programmatically until the above step is completed.

Endpoints πŸ”—

Version 5 Endpoints Version 4 Endpoint Description
GET /v5/lists 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 /v5/lists/{list_id} GET /v4/lists/{list_id} Get the existing list of a company by provided ID.
POST /v5/lists POST /v4/lists CREATE a new IAB category list and apply it to an app.
PUT /v5/lists/{list_id} 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 /v5/lists/{list_id} DELETE /v4/lists/{list_id} DELETE a given IAB category list, identifying list via ID.
GET /v5/apps/{app id}/monetization_settings GET /v4/apps/{app id}/monetization_settings Get the app ID’s current monetization settings.
PATCH /v5/apps/{app id}/monetization_settings PATCH /v4/apps/{app id}/monetization_settings UPDATE the app ID’s monetization setting.

Get a list of IAB Categories πŸ”—

Version 5 Version 4
GET /v5/lists GET /v4/lists

Retrieves all the available lists with pagination and filtering.

Required Headers πŸ”—

Authorization: Bearer {access-token}
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 /v5/lists
    Host: api.chartboost.com
    Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2J
    Content-Type: application/json;charset=UTF-8
    
  • GET /v4/lists
    Host: api.chartboost.com
    Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2J
    Content-Type: application/json;charset=UTF-8
    

Responses πŸ”—

  • 200 - OK Successful Response
  • 400 - Bad Request 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 πŸ”—

Version 5 Version 4
GET /v5/lists/{list_id} GET /v4/lists/{list_id}

Retrieves the current list by provided ID.

Required Headers πŸ”—

Authorization: Bearer {access-token}
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 πŸ”—

Version 5 Version 4
POST /v5/lists POST /v4/lists

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

Required Headers πŸ”—

Authorization: Bearer {access-token}
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 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 Request Response

200 OK Successful Response Example

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

Update an existing list by ID πŸ”—

Version 5 Version 4
PUT /v5/lists/{list_id} PUT /v4/lists/{list_id}

Updates an existing list by provided ID.

Required Headers πŸ”—

Authorization: Bearer {access-token}
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 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 Request 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 πŸ”—

Version 5 Version 4
DELETE /v5/lists/{list_id} DELETE /v4/lists/{list_id}

Deletes an existing list by provided ID.

Required Headers πŸ”—

Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8

Responses πŸ”—

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

Get the app’s monetization settings πŸ”—

Version 5 Version 4
GET /v5/apps/{app id}/monetization_settings GET /v4/apps/{app id}/monetization_settings

Get the app ID’s current monetization settings.

Required Headers πŸ”—

Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8

Parameters πŸ”—

Blocking Settings
ad_blocking_settings

Field Type Description
monetization_agefilter_check boolean Blocks adult oriented apps from showing ads in your app.
blocked_advertiser_store_ids array of strings The apps blocked from showing ads in your app.
blocked_iab_categories_v1_list string The blocked IAB categories’ list ID. If null, then the Default Category List (Taxonomy 1.0) is applied.

Ad Experience Settings
ad_experience_settings

Field Type Description
interstitial_allow_skip boolean Determines whether the interstitial ad can be skipped or not. Always set to true.
button_type string Determines type of skip button on video ads.
show_button_timer integer Seconds until the close button is visible.
default_muted boolean Determines whether the ad starts muted or not. When false, ads are not muted.
interstitial_max_duration integer Maximum duration for an interstitial ad to play in seconds.
rewarded_max_duration integer Maximum duration for a rewarded ad to play in seconds.

Ad Targeting Settings
ad_targeting_settings

Field Type Description
target_device_types schema The device types to include or exclude.
device_types array of strings The device types.
is_included boolean If false, the device types are excluded. If true, the device types are included.
target_os_version schema The min and max OS version to target. If null, then the app is targeting all OS versions.
min string The min OS version to target. If null, then no minimum value is defined.
max string The max OS version to target. If null, then no maximum value is defined.

Request Example πŸ”—

  • GET /v5/lists
    Host: api.chartboost.com
    Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2J
    Content-Type: application/json;charset=UTF-8
    
  • GET /v4/lists
    Host: api.chartboost.com
    Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2J
    Content-Type: application/json;charset=UTF-8
    

Responses πŸ”—

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

Response Example πŸ”—

{
    "ad_blocking_settings": {
        "monetization_agefilter_check": true,
        "blocked_advertiser_store_ids": [
            "123456789",
            "987654321"
        ],
        "blocked_iab_categories_v1_list": null
    },
    "ad_experience_settings": {
        "interstitial_allow_skip": true,
        "template_settings": {
            "button_type": "skip",
            "show_button_timer": 30,
            "default_muted": false
        },
        "video_duration_settings": {
            "interstitial_max_duration": 120,
            "rewarded_max_duration": 120
        }
    },
    "ad_targeting_settings": {
        "target_device_types": {
            "device_types": [
                "iPad Air (4th generation)",
                "iPad 8th gen"
            ],
            "is_included": false
        },
        "target_os_version": {
            "min": "16.5.1",
            "max": "17.0.1"
        }
    }
}

Update the app’s monetization settings πŸ”—

Version 5 Version 4
PATCH /v5/apps/{app id}/monetization_settings PATCH /v4/apps/{app id}/monetization_settings

UPDATE the app ID’s monetization setting.

Required Headers πŸ”—

Authorization: Bearer {access-token}
Content-Type: application/json;charset=UTF-8

Parameters πŸ”—

Blocking Settings ad_blocking_settings

Field Type Valid Values Description
monetization_agefilter_check boolean true or false Blocks adult oriented apps from showing ads in your app.
blocked_advertiser_store_ids array of strings list of store IDs Apps blocked from showing ads in your app.
blocked_iab_categories_v1_list string IAB categories ID or null The blocked IAB categories’ list ID. Set to null for the Default Category List (Taxonomy 1.0).

Ad Experience Settings ad_experience_settings

template_settings schema

Field Type Valid Values Description
button_type string skip, worded, close Determines type of skip button on video ads.
show_button_timer integer 5, 15, 30, 45, 60, 90 Seconds until the close button is visible.
default_muted boolean true or false Determines whether the ad starts muted or not. When false, ads are not muted.

video_duration_settings schema

Field Type Valid Values Description
interstitial_max_duration integer 5, 15, 30, 45, 60, 90, 120 Maximum duration for an interstitial ad to play in seconds.
rewarded_max_duration integer 5, 15, 30, 45, 60, 90, 120 Maximum duration for a rewarded ad to play in seconds.

Ad Targeting Settings ad_targeting_settings

target_device_types schema

Field Type Valid Values Description
device_types array of strings list of device type by model or series The device types by model or series to be included or excluded. List must contain only model types or only series types.
is_included boolean true or false If true, the device types are included. If false, the device types are excluded.

target_os_version schema

Field Type Valid Values Description
min string OS version number or null The min OS version to target. Enter null to clear the value.
max string OS version number or null The max OS version to target. Enter null to clear the value.

Request Example πŸ”—

{
    "ad_blocking_settings": {
        "monetization_agefilter_check": true,
        "blocked_advertiser_store_ids": [
            "123456789",
            "987654321"
        ],
        "blocked_iab_categories_v1_list": null
    },
    "ad_experience_settings": {
        "template_settings": {
            "button_type": "skip",
            "show_button_timer": 30,
            "default_muted": false
        },
        "video_duration_settings": {
            "interstitial_max_duration": 120,
            "rewarded_max_duration": 120
        }
    },
    "ad_targeting_settings": {
        "target_device_types": {
            "device_types": [
                "iPad Air (4th generation)",
                "iPad 8th gen"
            ],
            "is_included": false
        },
        "target_os_version": {
            "min": "16.5.1",
            "max": "17.0.1"
        }
    }
}

Responses πŸ”—

  • 200 - OK Successful Response
  • 400 - Bad Request
  • 404 - Validation Error Response