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 🔗

Make sure you have read and understood the section on API Access & Authentication.

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 /v4/apps/{app id}/monetization_settings`	Get the app ID’s current monetization settings.
`PATCH /v4/apps/{app id}/monetization_settings`	UPDATE the app ID’s monetization setting.

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 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 🔗

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 Request 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 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 🔗

DELETE /v4/lists/{list_id}

Deletes an existing list by provided ID.

Caution: Deleting lists cannot be undone. Any apps using this list will revert to using the Default Categories List (Taxonomy 1.0).

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

Get the app’s monetization settings 🔗

GET /v4/apps/{app id}/monetization_settings

Get the app ID’s current monetization settings.

Required Headers 🔗

                Authorization: {X-Chartboost-Company-ID, X-Chartboost-User-ID}
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 /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 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 🔗

PATCH /v4/apps/{app id}/monetization_settings

UPDATE the app ID’s monetization setting.

Required Headers 🔗

                Authorization: {X-Chartboost-Company-ID, X-Chartboost-User-ID}
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

Monetization

List Management API

Before You Get Started 🔗

Endpoints 🔗

Get a list of IAB Categories 🔗

Required Headers 🔗

Optional Parameters 🔗

Request Example 🔗

Responses 🔗

Summary (False) Long Response Example 🔗

Summary (True) Short Response Example 🔗

Get an existing list by ID 🔗

Required Headers 🔗

Parameters 🔗

Response Example 🔗

Responses 🔗

Create a new list 🔗

Required Headers 🔗

Parameters 🔗

Request Example 🔗

Responses 🔗

Update an existing list by ID 🔗

Required Headers 🔗

Request Example 🔗

Parameters 🔗

Responses 🔗

Delete an existing list by ID 🔗

Required Headers 🔗

Responses 🔗

Get the app’s monetization settings 🔗

Required Headers 🔗

Parameters 🔗

Request Example 🔗

Responses 🔗

Response Example 🔗

Update the app’s monetization settings 🔗

Required Headers 🔗

Parameters 🔗

Request Example 🔗

Responses 🔗