Managing Campaigns

Introduction

The campaign is the entity where you set the ad format and the countries you would like to run your ads for your app. Each campaign belongs to a partner account.

We support the following campaign types:

• playtime

• advance

• playtime_web

• interstitial_video.

Depending on your strategy, a campaign has the ability to target either a single GEO or multiple in one Campaign Group. For example:

• Campaign — US

• Campaign — US and CA

• Campaign — DE, FR, GB, SP, IT

Once your campaign is created, you are required to have at least 1 active targeting group to advertise.

All partner accounts will require a secret API token in order to use this API. Your adjoe account manager can provide this to you upon request.

Getting the list of campaigns

https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/campaigns

• %TOKEN%

  The token is a hex string, which is given to the advertiser by the account manager.

• Method:

  The http request type

  GET

• URL Query Parameters

  It is possible to exclusively query active campaigns. A campaign is considered active if at least one of its targeting groups is active. By default, all campaigns are returned. Therefore, you can include active in the query parameters. There is a limit on the amount of returned campaigns in the result. By default, only 1000 campaigns will be returned. The next batch of campaigns can then be obtained by making the request with the NextKey from the previous request as the paging_key. The number of campaigns to return is controlled by the limit parameter. If NextKey is missing or set to null you have reached the final page and there are no more results. Optional: active_only=true paging_key=eyJLZXkiOiJhYmMxMjMifQ== limit=100

• Success Response:

  When successful, the API responds with a http OK status code and a valid json object. There will be one item in Content for each campaign in the adjoe system.

  • Code: 200

    Content-Type: application/json; charset=utf-8

    Content:

    {
      "Content": [
          {
              "CampaignUUID": "00b8aaf6-b51c-407f-a680-cfba796779ad",
              "CampaignType": "playtime",
              "CampaignName": "Test campaign name",
              "BidType": "CPI",
              "ExternalID": "abc123",
              "AppID": "com.app.1",
              "Countries": [
                  "US",
                  "FR"
              ]
          },
          {
              "CampaignUUID": "10b8aaf6-b51c-407f-a680-cfba796779ad",
              "CampaignType": "advance",
              "CampaignName": "Another test campaign name",
              "BidType": "install",
              "ExternalID": "abc789",
              "AppID": "com.app.2",
              "Countries": [
                  "DE"
              ]
          }
      ],
      "NextKey": "eyJLZXkiOiJhYmMxMjMifQ=="
    }

  JSON Schema definition

  Attribute	Type	Description
  CampaignUUID	uuid_v4	The unique campaign UUID in the adjoe system.
  CampaignType	string	Type of the campaign, playtime | advance | insterstitial_video | rewarded_video | playtime_web
  CampaignName	string	Name of campaign
  BidType	string	Bid type of the campaign, only CPI
  ExternalID	string	The advertisers external ID for this campaign.
  AppID	string	The Playstore or AppStore app ID, e.g. com.app.1 for Android and 12345678 for iOS.
  Countries	array	The list of countries the campaign is live; this is a list of 2 letter country codes, following the ISO 3166-1 alpha-2 standard.

• Error Response:

  The API does respond with different status codes, depending on the error:

  • Code: 401 UNAUTHORIZED

    If the authorization fails, the API returns status code 401 with error message.

    Content-Type: application/json; charset=utf-8

    Content:

    {
        "error" : "invalid token"
    }

  • Code: 400 BAD REQUEST

    If one of the URL parameters has a wrong format, the API returns status code 400 with error specific message.

    Content-Type: application/json; charset=utf-8

    Content:

    {
        "error": "active_only format is wrong. Please use true or false."
    }

• Sample Curl Call:

        curl -X GET \
        'https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/campaigns?ac

Updating a single campaign

https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/campaign/%CAMPAIGN_UUID%

• %TOKEN%

  The token is a hex string, which is given to the advertiser by the account manager.

• %CAMPAIGN_UUID%

  The unique UUID of the campaign obtained by previously fetching the available campaigns.

• Method:

  The http request type

  PUT

• Request body

  Content

   {
     "Countries": ["US", "FR"],
     "ExternalID": "my-external-id"
   }

  Fields that are not included in the json body are considered to be un-changed. CampaignUUID and AppID cannot be updated.

• Success Response:

  When successful, the API responds with a http OK status code and a valid json object.

  • Code: 200

    Content-Type: application/json; charset=utf-8

    Content:

    {
        "CampaignUUID": "00b8aaf6-b51c-407f-a680-cfba796779ad",
        "CampaignType": "playtime",
        "BidType": "install",
        "ExternalID": "abc123",
        "AppID": "com.app.1",
        "Countries": [
            "US",
            "FR"
        ]
    }

  JSON schema definition

  Attribute	Type	Description
  CampaignUUID	uuid_v4	The unique campaign UUID in the adjoe system.
  CampaignType	string	Type of the campaign, playtime | advance | insterstitial_video | rewarded_video | playtime_web
  BidType	string	Bid type of the campaign, only CPI
  ExternalID	string	The partners external ID for this campaign.
  AppID	string	The playstore or appstore app ID, e.g. com.app.1 for Android and 12345678 for iOS.
  Countries	array of string	The list of countries this campaign is live; this is a list of 2 letter country codes according to the ISO 3166-1 alpha-2 standard. In particular the country code of the United Kingdom is GB.

• Error Response:

  The API does respond with different status codes, depending on the error:

  • Code: 401 UNAUTHORIZED

    If the authorization fails, the API returns status code 401 with error message.

    Content-Type: application/json; charset=utf-8

    Content:

    {
        "error" : "invalid token"
    }

  • Code: 404 NOT FOUND

    If the campaign does not exist.

    Content-Type: application/json; charset=utf-8

    Content:

    {
        "error": "campaign not found"
    }

• Sample Curl Call:

  curl -X PUT \
    'https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/campaign/cdcc59d8-f67e-410d-8700-7b48a50c4b58' \
    --data-raw '{"Countries":["US","FR"]}'

Getting a single campaign by it's UUID

https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/campaigns/%UUID%

• %TOKEN%

  The token is a hex string, which is given to the advertiser by the account manager.

• %UUID%

  The key is a UUIDV4 string, which is assigned to a campaign resource on creation.

• Method:

  The http request type

  GET

• Success Response:

  When successful, the API responds with a http OK status code, and a valid json object. There will be one item in Content for each campaign in the adjoe system.

  • Code: 200

    Content-Type: application/json; charset=utf-8

    Content:

      {
          "CampaignUUID": "00b8aaf6-b51c-407f-a680-cfba796779ad",
          "CampaignType": "playtime",
          "CampaignName": "Test campaign name",
          "BidType": "install",
          "ExternalID": "abc123",
          "AppID": "com.app.1",
          "Countries": [
              "US",
              "FR"
          ]
      }

  JSON schema definition

  Attribute	Type	Description
  CampaignUUID	uuid_v4	The unique campaign UUID in the adjoe system.
  CampaignType	string	Type of the campaign, playtime | advance | insterstitial_video | rewarded_video | playtime_web
  CampaignName	string	Name of campaign
  BidType	string	Bid type of the campaign, only install
  ExternalID	string	The advertisers external ID for this campaign.
  AppID	string	The playstore or appstore app ID, e.g. com.app.1 for Android and 12345678 for iOS.
  Countries	array	The list of countries the targeting groups campaign is live; this is a list of 2 letter country codes.

• Error Response:

  The API does respond with different status codes, depending on the error:

  • Code: 401 UNAUTHORIZED

    If the authorization fails, the API returns status code 401 with error message.

    Content-Type: application/json; charset=utf-8

    Content:

    {
        "error" : "invalid token"
    }

  • Code: 400 BAD REQUEST

    If one of the URL parameters has a wrong format, the API returns status code 400 with error specific message.

    Content-Type: application/json; charset=utf-8

    Content:

    {
        "error": "active_only format is wrong. Please use true or false."
    }

• Sample Curl Call:

  curl -X GET \
    'https://prod.adjoe.zone/v2/campaign-management-api/public/%TOKEN%/campaigns/%KEY%'