API Access & Overview

With the Chartboost API, you can access campaign and app analytics, retrieve account and earnings information and more.

Note: In June 2024, Chartboost introduces API version 5 for the analytics API. Support for WHAPI (v2.whapi.chartboost.com) will be sunsetting soon. Any new API endpoints will only be available for version 5 moving forwards.

Before you get started 🔗

Complete the Version 5 API access setup for the following API:

Alert: The campaign and account APIs are sunsetted.

Version 5 API access setup 🔗

URL: https://api.chartboost.com/v5/

Obtaining your API client credentials 🔗

The Chartboost API uses the OAuth2 standard protocol for “Client Credentials Grant” (RFC ft-ietf-oauth-v2: The OAuth 2.0 Authorization Framework) to grant authorization.

A client must pass a client_id and client_secret value to obtain an access token for authentication.

To find your client ID and client secret:

Log in to your Chartboost platform.
Click on your user icon at the top right corner.
Select Company info & settings.
Select Access Management from the left navigation column.
Click on Refresh API v5 Credentials to obtain new client ID and client secret credentials.
- For v4 users, click on Refresh API v4 Credentials to obtain your client ID and client secret credentials.
- The client secret key is only displayed when you refresh the credentials. You will not be able to see it again once you refresh or leave this page. If you loose your client secret key, you will have to re-authenticate with a new client ID and secret credentials.

Authentication 🔗

An access token is required to access and make requests to the Chartboost public API server. Obtain your access token by passing in your client id and client secret credentials to the authentication server.

Endpoint POST /v5/oauth/token
URL https://api.chartboost.com/v5/oauth/token

Send a request to the OAuth2 token endpoint using your client ID and client secret credentials in the request body. (Client Credentials Flow: Request tokens)

                POST /v5/oauth/token HTTP/1.1
Host: api.chartboost.com
Content-Type: application/json

{
  "client_id": YOUR_CLIENT_ID,
  "client_secret": YOUR_CLIENT_SECRET,
  "audience": "https://public.api.gateway.chartboost.com",
  "grant_type": "client_credentials"
}

              

The authorization server will validate and respond with an access token and expiration time in seconds; effective immediate. You must acquire a new access token after expiration, but you can use the same client credentials.

                HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in":86400,
  "scope":"apps:adv:get sa:new apps:crea:new comp:get..."
}

              

Using the public API 🔗

After authenticating against the Public API, every subsequent call must use the obtained Access Token to grant access to the protected resources. To do so, the client must use the Authorization Header with the “Bearer” token (as described in RFC ft-ietf-oauth-v2-bearer: The OAuth 2.0 Authorization Framework: Bearer Token Usage). Client call example:

Header example

                GET /v5/apps HTTP/1.1
Host: api.chartboost.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

              

Troubleshooting authentication errors 🔗

Any issue with the authentication will produce an error from the list below (as described in RFC 6749 - Section 5.2. Error Response):

Parameter	Response
`error`	REQUIRED. A single ASCII [USASCII] error code. Values for the “error” parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
`error_description`	OPTIONAL. Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the “error_description” parameter MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
`error_uri`	OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the “error_uri” parameter MUST conform to the URI-reference syntax and thus MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E.
`invalid_request`	The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
`invalid_client`	Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the “Authorization” request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the “WWW-Authenticate” response header field matching the authentication scheme used by the client.
`invalid_grant`	The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
`unauthorized_client`	The authenticated client is not authorized to use this authorization grant type.
`unsupported_grant_type`	The authorization grant type is not supported by the authorization server.
`invalid_scope`	The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

                HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_request"
}

              

Chartboost API Rules 🔗

These guidelines help us ensure that all customers’ requests are returned quickly. If you do not respect these limits, your API access will be limited.

Group your apps into a single request. Instead of sending a unique API request for each app, drop the appId parameter and let the API return data for all the apps.

Advertising