# 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](https://github.com/InteractiveAdvertisingBureau/Taxonomies/blob/main/Content%20Taxonomies/Content%20Taxonomy%201.0.tsv){:target="_blank"} list.

## Before You Get Started

Before you get started, complete the [API Access & Authentication](/en/monetization/reference/api-access-authentication/#api-access-url-endpoint) process.

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


## Endpoints

<div class="alert alert-info" role="alert">
  <b>Note:</b> In June 2024, Chartboost introduces API <b>version 5</b>. Support for version 4 will continue until further notice. However, any new API endpoints will only be available for version 5 moving forwards.
</div>

| Version 5 Endpoints | Version 4 Endpoint                                           | Description            |
| ------------------- | :----------------------------------------------------------- | :--------------------- |
| [`GET /v5/lists`](#get-a-list-of-iab-categories) | [`GET /v4/lists`](#get-a-list-of-iab-categories) | 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-an-existing-list-by-id) | [`GET /v4/lists/{list_id}`](#get-an-existing-list-by-id) | Get the existing list of a company by provided ID. |
| [`POST /v5/lists`](#create-a-new-list) | [`POST /v4/lists`](#create-a-new-list)  | CREATE a new IAB category list and apply it to an app. |
| [`PUT /v5/lists/{list_id}`](#update-an-existing-list-by-id) | [`PUT /v4/lists/{list_id}`](#update-an-existing-list-by-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-an-existing-list-by-id) | [`DELETE /v4/lists/{list_id}`](#delete-an-existing-list-by-id) | DELETE a given IAB category list, identifying list via ID. |
| [`GET /v5/apps/{app id}/monetization_settings`](#get-the-apps-monetization-settings) | [`GET /v4/apps/{app id}/monetization_settings`](#get-the-apps-monetization-settings) | Get the app ID’s current monetization settings. |
| [`PATCH /v5/apps/{app id}/monetization_settings`](#update-the-apps-monetization-settings) | [`PATCH /v4/apps/{app id}/monetization_settings`](#update-the-apps-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

```text
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

<ul class="tab" data-tab="879f165f-caba-47a4-800d-424748667749" data-name="apiGetLists">
  
      <li class="active">
          <a href="#">Version 5 </a>
      </li>
  
      <li>
          <a href="#">Version 4 </a>
      </li>
  
</ul>
<ul class="tab-content" id="879f165f-caba-47a4-800d-424748667749" data-name="apiGetLists">
  
      <li class="active">
<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /v5/lists
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2J
Content-Type: application/json;charset=UTF-8
</code></pre></div></div>
</li>
  
      <li>
<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /v4/lists
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2J
Content-Type: application/json;charset=UTF-8
</code></pre></div></div>
</li>
  
</ul>


#### Responses

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



#### Summary (False) Long Response Example

```javascript
{
  "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

```javascript
{
  "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

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

#### Parameters

|Field|Type|Description|
|-----|----|-----------|
|id|string|ID of the list.|


#### Response Example

```javascript
{
  "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

```text
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](https://github.com/InteractiveAdvertisingBureau/Taxonomies/blob/main/Content%20Taxonomies/Content%20Taxonomy%201.0.tsv){:target="_blank"}. 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

```javascript
{
  "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
```javascript
{
  "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

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

#### Request Example

```javascript
{
  "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](https://github.com/InteractiveAdvertisingBureau/Taxonomies/blob/main/Content%20Taxonomies/Content%20Taxonomy%201.0.tsv){:target="_blank"}. 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
```javascript
{
  "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.  

<div class="alert alert-warning" role="alert">
  <b>Caution:</b> Deleting lists cannot be undone. Any apps using this list will revert to using the Default Categories List (Taxonomy 1.0).
</div>

#### Required Headers

```text
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

```text
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

<ul class="tab" data-tab="882723c0-9e37-49f3-8a55-a4600ab8f10d" data-name="apiGetAppMonSetting">
  
      <li class="active">
          <a href="#">Version 5 </a>
      </li>
  
      <li>
          <a href="#">Version 4 </a>
      </li>
  
</ul>
<ul class="tab-content" id="882723c0-9e37-49f3-8a55-a4600ab8f10d" data-name="apiGetAppMonSetting">
  
      <li class="active">
<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /v5/lists
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2J
Content-Type: application/json;charset=UTF-8
</code></pre></div></div>
</li>
  
      <li>
<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /v4/lists
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2J
Content-Type: application/json;charset=UTF-8
</code></pre></div></div>
</li>
  
</ul>


#### Responses

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

#### Response Example

```json
{
    "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

```text
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

```json
{
    "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