Ad Locations API

The ad location API allows the ability to obtain and update ad location details as well as creating and deleting ad locations for a given app.

Before you get started 🔗

Complete the API Access & Authentication process.

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

Endpoints 🔗

Get all 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 BIDDING, 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:

• Version 5
• Version 4

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

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

200 OK Response Example:

{
    "items": [
        {
            "uuid": "a0f68cce-f7f8-4c62-9137-dcfdf348d5b9",
            "name": "Bidding_INT_Next_Level",
            "ad_type": "interstitial",
            "type": "bidding"
        }
    ]
}

Create a new Ad Location 🔗

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

country_targeting 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.

bidding Request Example:

• Version 5
• Version 4

• POST /v5/apps/5c37c51476f3910c3cf92534/ad-locations HTTP/1.1
  Host: api.chartboost.com
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json; charset=UTF-8
  
  {
    "name": "bidding_via_api",
    "type": "bidding",
    "ad_type": "rewarded"
  }
  

• POST /v4/apps/5c37c51476f3910c3cf92534/ad-locations HTTP/1.1
  Host: api.chartboost.com
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
  Content-Type: application/json; charset=UTF-8
  
  {
    "name": "bidding_via_api",
    "type": "bidding",
    "ad_type": "rewarded"
  }
  

200 OK Response Example:

{
    "uuid": "90913206-0d74-4227-b134-dcb06610595f",
    "name": "bidding_via_api",
    "ad_type": "rewarded",
    "type": "bidding"
}

400 Error Example:

{
    "detail": [
        {
            "msg": "country_targeting can only be set for fixed_cpm ad_locations",
            "type": "cannot_set_country_target"
        }
    ]
}

fixed_cpm Request Example:

• Version 5
• Version 4

• POST /v5/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
      }
    ]
  }
  

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

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:

• Version 5
• Version 4

• PATCH /v5/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
      }
    ]
  }
  

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

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:

• Version 5
• Version 4

• DELETE /v5/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
  

• 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