Ad Locations API

Before You Get Started 🔗

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

You will not be able to create or manage your Ad-Locations programmatically until the above step is completed.

Endpoints 🔗

Get all Ad-Locations 🔗

GET /v4/apps/{app_id}/ad-locations

Get a list of all ad-locations belonging to the given app_id.

Required Headers

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

Optional Parameters

Behavior

If no query parameters are provided, this route returns a response containing all ad-locations belonging to an app whether they are FIXED_CPM, AUTO_CPM, or CROSSPROMO and regardless of ad-type i.e. rewarded, banner, or interstitial.

• If the type_filter query param is provided, only ad-locations that belong to the specified type are returned.
• If the ad_type_filter query param is provided only ad-locations that belong to the specified ad_type are returned.

Request Example:

GET /v4/apps/5c37c51476f3910c3cf92534/ad-locations?type_filter="fixed_cpm" HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

200 OK Response Example:

{
    "items": [
        {
            "uuid": "2f5fa6d4-fa06-49d1-88f6-85e2066001cf",
            "name": "test_location_1",
            "ad_type": "interstitial",
            "type": "fixed_cpm",
            "country_targeting": [
                {
                    "country": "US",
                    "price": 6.0
                },
                {
                   "country": "CA",
                   "price": 2.55
                }
            ]
        },
        ...
    ]
}

Create a new Ad-Location 🔗

POST /v4/apps/{app_id}/ad-locations

Create a new ad-location belonging to the given app_id.

Required Headers

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

Request Body Fields

CountryTargeting Schema

Restrictions
There are some restrictions about what ad-locations can be created. These restrictions are there to prevent monetization issues that could arise from naming conflicts.

• Uniqueness Restriction:
  For a given app, there can never be multiple ad-locations with the same combination of (name + ad_type). This means that for a given name, there can be at most exactly 3 ad-locations with the same name. Example:
  • name: “GameOver”, ad_type: “interstitial”, …
  • name: “GameOver”, ad_type: “rewarded”, …
  • name: “GameOver”, ad_type: “banner”, …
• Replacement Restriction:
  A newly created “fixed_cpm” ad-location cannot have the same (name + ad_type) of an existing ad-location. If that is the case, the API will return an error to prevent overwriting existing locations. The only exception is when the existing ad-location is of type “auto_cpm” at which point it will get replaced by the newly created “fixed_cpm” ad-location.

Request Example:

POST /v4/apps/5c37c51476f3910c3cf92534/ad-locations HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

{
  "name": "example",
  "type": "fixed_cpm",
  "ad_type": "rewarded",
  "country_targeting": [
    {
      "country": "DE",
      "price": 29.99
    },
    {
      "country": "FR",
      "price": 15.55
    }
  ]
}

200 OK Response Example:

{
    "uuid": "00af4377-c503-4559-b50f-37950bf9acd7",
    "name": "example",
    "ad_type": "rewarded",
    "type": "fixed_cpm",
    "country_targeting": [
        {
            "country": "DE",
            "price": 29.99
        },
        {
            "country": "FR",
            "price": 15.55
        }
    ]
}

400 Error Example:

{
    "detail": [
        {
            "msg": "A fixed_cpm location with the same name and ad-type already exists",
            "type": "existing_fixed_cpm"
        }
    ]
}

Update an Ad-Location 🔗

PATCH /v4/apps/{app_id}/ad-locations/{ad_location_uuid}

Updates an existing ad-location belonging to the given app_id and matching the given uuid.

Required Headers

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

Special Considerations

• For fixed_cpm locations the country_targeting field is fully overwritten with the new value if it is sent in the request.
• Fields such as uuid, ad_type, and type cannot be updated in order to preserve the integrity of the analytics data. Instead, it is recommended to delete the entire ad-location and create a new one in order to achieve the same result.
• A change to the name value cannot violate the uniqueness restriction mentioned above.

Request Example:

PATCH /v4/apps/5c37c51476f3910c3cf92534/ad-locations/00af4377-c503-4559-b50f-37950bf9acd7 HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

{
  "country_targeting": [
    {
      "country": "default",
      "price": 5.00
    }
  ]
}

Response Example:

{
    "uuid": "00af4377-c503-4559-b50f-37950bf9acd7",
    "name": "example",
    "ad_type": "rewarded",
    "type": "fixed_cpm",
    "country_targeting": [
        {
            "country": "default",
            "price": 5.00
        }
    ]
}

Delete an Ad-Location 🔗

DELETE /v4/apps/{app_id}/ad-locations/{ad_location_uuid}

Deletes a single ad-location belonging to the given app_id and matching the given uuid.

Required Headers

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

Request Example:

DELETE /v4/apps/5c37c51476f3910c3cf92534/ad-locations/00af4377-c503-4559-b50f-37950bf9acd7 HTTP/1.1
Host: api.chartboost.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json;charset=UTF-8

Response Example:

204 No Content