Advertising

App Management API

The app management API allows the ability to obtain and update app details as well as creating and deleting apps.

Before you get started 🔗

  1. Review and accept the Chartboost App Disclosures on the User Access Management page in the Chartboost platform.
  2. Complete the API Access & Authentication process.

You will not be able to create or manage your apps programmatically until the above steps are completed.

Endpoints 🔗

Endpoint Description
GET /v5/apps Get a list of apps
POST /v5/apps Create a new app
GET /v5/apps/{app_id} Get a single app by ID
DELETE /v5/apps/{app_id} Delete an app by ID
PATCH /v5/apps/{app_id} Update an app by ID

Get a list of apps 🔗

GET /v5/apps

Retrieves all the apps belonging to a company.

Required Headers

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

Optional Request Parameters

Field Type Description
keyword_filter string A keyword to filter by. Applies to app name or nickname.
platform_filters string Filter by platform (“android”, “ios”, “amazon”)
direction string Sort direction (“asc”, “desc”)
page int Requested page number
limit int Amount of items per page. (default = 25)

Request Example:

GET /v5/apps?page=1&limit=5 HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

Response Parameters

Field Description
id The app’s ID.
nickname A given nickname for the app. This does not have to match the app name in the app store.
icon The official icon URL extracted from the app store.
platform Specifies the app platform ios, android, or amazon.
is_live Indicates whether the app is live in the app store or not.
store_app_id Indicates the app ID in the app store.
name The name of the app in the app-store.
publishing_application States details on whether the app has been approved or rejected by Chartboost, reasons for rejection, and date reviewed.
metadata States number of ad locations for a given ad format.

200 OK Successful Response Example:

{
    "items": [
        {
            "id": "64054c7decf2fc7b954e98d2",
            "nickname": "Android Test App",
            "icon": "https://play-lh.googleusercontent.com/Gz9uP4jwKhNb942ykXrIuGfza3a31p6GpJ2YdPStC7CivobAHKayDSR5QSrruauZZ1k=s180",
            "platform": "android",
            "is_live": true,
            "store_app_id": "com.kathleenOswald.solitaireGooglePlay",
            "name": "Solitaire + Card Game by Zynga",
            "publishing_application": {
                "status": "Rejected",
                "created_at": 1683312886,
                "reviewed_by": "624b2f1471a86307cc1621bc",
                "reviewed_at": 1683531176,
                "reviewer_notes": "",
                "reject_reason": "dau",
                "reject_detail": "low-dau",
                "rejected_at": 1683531176
            },
            "metadata": {
                "ad_location_counts": {
                    "interstitial": 7,
                    "rewarded": 1,
                    "banner": 0
                }
            }
        }
    ],
  "page": 1,
  "limit": 5,
  "total": 1
}

400 Validation Error Example:

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Create a new App 🔗

POST /v5/apps

Creates an app from the given input data and retrieves a partial representation of the created app.

Required Headers

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

Request Parameters

Field Type Required/Optional Description
nickname string Required A given nickname for the app. This does not have to match the app name in the app store.
name string Optional The name of the app in the app-store. If not provided, this value will automatically be set once the app is live in an app store.
orientations string[] Required An array of supported app orientations. Values accepted are landscape and portrait.
default_orientation string Optional Required whenever the orientations field specifies both landscape and portrait at the same time. In such a case, the default_orientation field will specify which one is to be treated as default.
is_live boolean Required Indicates whether the app is live in the app store or not.
store_app_id string Optional This field is always required when is_live = true. It is used to indicate the app ID in the app store.
store_app_url string Optional This field is always required when is_live = true. It is used to indicate the app’s official app store URL.
store_bundle_id string Optional This field is always required when is_live = true. it is used to indicate the app’s official bundle ID in the app store.
is_test_mode_on boolean Required Indicates whether the app is in test_mode or not.
test_mode_duration integer Optional Specifies the duration in minutes until test mode expires. This field is optional and only effective when is_test_mode_on = true. If test mode is set true and this field is not provided, then test mode will be enabled indefinitely.
is_directed_at_kids_under_13 string Required Specifies whether the app is directed at kids under 13 or not, the value is required and must be either YES or NO to adhere to COPPA Regulations.
platform string Required Specifies the app platform ios, android, or amazon.

Request Example:

POST /v5/apps HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

{
  "nickname": "example app",
  "orientations": [
    "portrait"
  ],
  "is_live": true,
  "is_test_mode_on": false,
  "store_app_id": "com.chartboost.example",
  "store_app_url": "https://play.google.com/store/apps/example",
  "store_bundle_id": "com.chartboost.example",
  "is_directed_at_kids_under_13": "NO",
  "platform": "android"
}

200 OK Successful Response Example:

{
    "id": "64054c7decf2fc7b954e98d2",
    "nickname": "example app",
    "orientations": [
        "portrait"
    ],
    "default_orientation": "portrait",
    "platform": "android",
    "is_live": true,
    "signature": "{app signature}",
    "is_coppa_disclosure_read": true,
    "is_sdk_active": false,
    "is_test_mode_on": false,
    "store_app_id": "com.chartboost.com",
    "store_app_url": "https://play.google.com/store/apps/example",
    "store_bundle_id": "com.chartboost.example",
    "is_directed_at_kids_under_13": "NO"
}

Get a single app by ID 🔗

GET /v5/apps/{app_id}

Retrieves a single app for the given ID if it exists.

Required Headers

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

Request Example

GET /v5/apps/64054c7decf2fc7b954e98d2 HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

Response Parameters

Field Description
id The app’s ID.
nickname A given nickname for the app. This does not have to match the app name in the app store.
orientations An array of supported app orientations.
default_orientation Specifies which orientation is to be treated as default when both orientations are listed in orientations.
platform Specifies the app platform ios, android, or amazon.
is_live Indicates whether the app is live in the app store or not.
signature The app’s signature ID.
is_coppa_disclosure_read States whether user has accepted the Chartboost App disclosure.
is_sdk_active States whether the SDK is active or not.
is_test_mode_on Indicates whether the app is in test mode.
test_mode_duration Specifies the duration in minutes until test mode expires. This field is only effective when is_test_mode_on = true. If test mode is set true and this field is not provided, then test mode will be enabled indefinitely.
name The name of the app in the app-store.
icon The official icon URL extracted from the app store.
store_app_id Indicates the app ID in the app store.
store_app_url Indicates the app’s official app store URL.
store_bundle_id Indicate the app’s official bundle ID in the app store.
publishing_application States details on whether the app has been approved or rejected by Chartboost, reasons for rejection, and date reviewed.
app_ads_txt_status Indicates the app’s app-ads.txt status.
metadata States number of ad locations for a given ad format.
is_directed_at_kids_under_13 Specifies whether the app is directed at kids under 13 or not.

200 OK Successful Response Example:

{
    "id": "64054c7decf2fc7b954e98d2",
    "nickname": "android_test_app",
    "orientations": [
        "landscape",
        "portrait"
    ],
    "default_orientation": "landscape",
    "platform": "android",
    "is_live": false,
    "signature": "05908d540aecdb0d6eae6f43d5806769dfa33b2c",
    "is_coppa_disclosure_read": true,
    "is_sdk_active": false,
    "is_test_mode_on": true,
    "test_mode_duration": null,
    "name": null,
    "icon": null,
    "store_app_id": null,
    "store_app_url": null,
    "store_bundle_id": null,
    "publishing_application": {
        "status": "Approved",
        "created_at": 1699652507,
        "reviewed_by": "automatic_review",
        "reviewed_at": 1699652507,
        "reviewer_notes": "",
        "reject_reason": null,
        "reject_detail": null,
        "rejected_at": null
    },
    "app_ads_txt_status": null,
    "metadata": {
        "ad_location_counts": {
            "interstitial": 0,
            "rewarded": 1,
            "banner": 0
        }
    },
    "is_directed_at_kids_under_13": "NO"
}

404 Not Found Example Error:

{
    "detail": [
        {
            "msg": "There is no app with ID 64054c7decf2fc7b954e98d2",
            "type": "not_found"
        }
    ]
}

Delete an App 🔗

DELETE /v5/apps/{app_id}

Deletes the app identified by the given app_id.
This operation performs a soft deletion of the app i.e., it just marks the app as deleted.

Required Headers

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

Request Example:

DELETE /v5/apps/64054c7decf2fc7b954e98d2 HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

204 Successful Response Example:

204 No Content

Update an App 🔗

PATCH /v5/apps/{app_id}

Updates the app identified by the given app_id and retrieves an updated version of the given app data payload.

Required Headers

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

Request Parameters

Field Type Required/Optional Description
orientations string[] Optional An array of supported app orientations. Values accepted are landscape and portrait.
default_orientation string Optional Required whenever the orientations field specifies both landscape and portrait at the same time. In such a case, the default_orientation field will specify which one is to be treated as default.
is_live boolean Optional Indicates whether the app is live in the app store or not. Cannot be changed from true to false.
store_app_id string Optional This field is always required when is_live = true. Indicates the app ID in the app store. Cannot be changed to null.
store_app_url string Optional This field is always required when is_live = true. Indicates the app’s official app store URL. Cannot be changed to null.
store_bundle_id string Optional This field is always required when is_live = true. Indicate the app’s official bundle ID in the app store. Cannot be changed to null.
is_test_mode_on boolean Optional Indicates whether the app is in test_mode or not.
test_mode_duration integer Optional Specifies the duration in minutes until test mode expires. This field is optional and only effective when is_test_mode_on = true. If test mode is set true and this field is not provided, then test mode will be enabled indefinitely.
is_directed_at_kids_under_13 string Optional Specifies whether the app is directed at kids under 13 or not, the value is required and must be either YES or NO to adhere to COPPA Regulations.

Request Example:

PATCH /v5/apps/64054c7decf2fc7b954e98d2 HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

{
  "nickname": "example app",
  "orientations": [
    "portrait",
    "landscape"
  ],
  "default_orientation": "landscape"
}

Response Parameters

Field Description
nickname A given nickname for the app. This does not have to match the app name in the app store.
name The name of the app in the app-store.
icon The official icon URL extracted from the app store.
publishing_application States details on whether the app has been approved or rejected by Chartboost, reasons for rejection, and date reviewed.
is_sdk_active States whether the SDK is active or not.
is_coppa_disclosure_read States whether user has accepted the Chartboost App disclosure.
platform Specifies the app platform ios, android, or amazon.
orientations An array of supported app orientations.
default_orientation Specifies which orientation is to be treated as default when both orientations are listed in orientations.
is_live Indicates whether the app is live in the app store or not.
store_app_id Indicates the app ID in the app store.
store_app_url Indicates the app’s official app store URL.
store_bundle_id Indicate the app’s official bundle ID in the app store.
is_test_mode_on Indicates whether the app is in test mode.
test_mode_duration Specifies the duration in minutes until test mode expires. This field is only effective when is_test_mode_on = true. If test mode is set true and this field is not provided, then test mode will be enabled indefinitely.
is_directed_at_kids_under_13 Specifies whether the app is directed at kids under 13 or not.

200 OK Successful Response Example:

{
    "id": "64054c7decf2fc7b954e98d2",
    "nickname": "example app",
    "orientations": [
        "portrait",
   "landscape"
    ],
    "default_orientation": "landscape",
    "platform": "android",
    "is_live": true,
    "signature": "{app signature}",
    "is_coppa_disclosure_read": true,
    "is_sdk_active": false,
    "is_test_mode_on": false,
    "store_app_id": "com.chartboost.com",
    "store_app_url": "https://play.google.com/store/apps/example",
    "store_bundle_id": "com.chartboost.example",
    "is_directed_at_kids_under_13": "NO",
    "publishing_application": {
        "status": "Approved",
        "created_at": 1686315670,
        "reviewed_by": "automatic_review",
        "reviewed_at": 1686315670,
        "reviewer_notes": "",
        "reject_reason": null,
        "reject_detail": null,
        "rejected_at": null
    }
}