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 🔗

Get a list of IAB Categories 🔗

Retrieves all the available lists with pagination and filtering.

Required Headers 🔗

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

Optional Parameters 🔗

Request Example 🔗

• Version 5
• Version 4

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

Retrieves the current list by provided ID.

Required Headers 🔗

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

Parameters 🔗

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 🔗

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 🔗

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 🔗

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 🔗

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 🔗

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 🔗

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

Ad Experience Settings
ad_experience_settings

Ad Targeting Settings
ad_targeting_settings

Request Example 🔗

• Version 5
• Version 4

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

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

Ad Experience Settings ad_experience_settings

template_settings schema

video_duration_settings schema

Ad Targeting Settings ad_targeting_settings

target_device_types schema

target_os_version schema

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