Basics of the AdUp API

Overview

With our AdUp API, you can sit back and automatically transfer all your account data into your preferred BI system.

Procedure

Before you start

To be able to use the AdUp API, create an account access. To do this, go to Profile in your account or read more in the corresponding support article.

Step 1

Obtain your API login details (e.g. via the frontend).

Step 2

Get an access token from the API via OAUTH.

Step 3

Now use the access token to access the Reports route. Take a look at the interactive documentation.

Step 4

Then set up your personal API requests. You can find code examples, descriptions of all fields as well as notes and links to all possible reports further down in this article. 

Authentication & Access Token

Step 1: Obtain API access details

Make sure you have your API access details ready.

Step 2: Request an access token

Send an HTTP POST request to the token endpoint https://api.adup-tech.com/v202101/oauth2/token.

Example:

curl -X POST \
  https://api.adup-tech.com/v202101/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

curl -X POST \
  https://api.adup-tech.com/v202101/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

curl -X POST \
  https://api.adup-tech.com/v202101/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

• grant_type: The type of grant, e.g. client_credentials.

• client_id: Your client ID.

• client_secret: Your client secret.

Step 3: Use the access token

Upon successful authentication, you will receive a response with the access token. You can use this token to access protected API resources by including it in the HTTP header of your API requests:

curl -X GET \
  https://api.adup-tech.com/v202101/your-api-endpoint \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

curl -X GET \
  https://api.adup-tech.com/v202101/your-api-endpoint \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

curl -X GET \
  https://api.adup-tech.com/v202101/your-api-endpoint \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Replace YOUR_ACCESS_TOKEN with the token you received and adjust the URL accordingly.

Additional notes:

• Please note that access tokens have a limited validity period and must be renewed regularly.

• Responses are in JSON format, for more information see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept

• The use of Postman is described here: https://learning.postman.com/docs/sending-requests/authorization/oauth-20/#using-client-credentials

Report Request

Code

{
  "report_name": "Test Report",
  "report_type": "CAMPAIGN_PERFORMANCE_REPORT",
  "select": [
    "Month",
    "CampaignName",
    "Clicks"
  ],
  "conditions": [
    {
      "field": "Clicks",
      "operator": "GREATER_THAN",
      "values": [
        "0"
      ]
    }
  ],
  "download_format": "JSON",
  "date_range_type": "LAST_MONTH"

{
  "report_name": "Test Report",
  "report_type": "CAMPAIGN_PERFORMANCE_REPORT",
  "select": [
    "Month",
    "CampaignName",
    "Clicks"
  ],
  "conditions": [
    {
      "field": "Clicks",
      "operator": "GREATER_THAN",
      "values": [
        "0"
      ]
    }
  ],
  "download_format": "JSON",
  "date_range_type": "LAST_MONTH"

{
  "report_name": "Test Report",
  "report_type": "CAMPAIGN_PERFORMANCE_REPORT",
  "select": [
    "Month",
    "CampaignName",
    "Clicks"
  ],
  "conditions": [
    {
      "field": "Clicks",
      "operator": "GREATER_THAN",
      "values": [
        "0"
      ]
    }
  ],
  "download_format": "JSON",
  "date_range_type": "LAST_MONTH"

Notes

Segmentation

To obtain statistics with a higher level of detail, you can use segmentation.

For example, to get statistics only for mobile devices, you must filter by device type.

In this case, you will want to segment your report by DeviceType. For instance, if you add the Device field to a Campaign Performance Report, you will get a report with one row for each campaign and device type combination, showing the statistical values (impressions, clicks, conversions, etc.) split across them. Note that the number of rows can increase exponentially for each additional segment field included in your report.

Implicit segmentation Each report is grouped by a key. For example, the Campaign Performance Report is implicitly segmented by CampaignId.

Rows without metrics

The report may contain rows that do not have values in the metrics. This can be caused by non-deliverable items or items paused within the requested period.

To include rows without metrics, you can set includeZeroImpressions to true (default) in the header. This can be used, for example, to create a structure report that contains all available elements of the account.

However, to reduce the number of rows when there are many elements without data, includeZeroImpressions should be set to false. Alternatively, a filter on metrics in conditions can be used.

Date ranges

For any date_range_type other than CUSTOM_DATE, only date_range_type is required.

"date_range": {

    "min": "2021-10-29",

    "max": "2021-10-29"

  },

  "date_range_type": "CUSTOM_DATE"

"date_range": {

    "min": "2021-10-29",

    "max": "2021-10-29"

  },

  "date_range_type": "CUSTOM_DATE"

"date_range": {

    "min": "2021-10-29",

    "max": "2021-10-29"

  },

  "date_range_type": "CUSTOM_DATE"

Micro Amount data type

Some fields have the Micro Amount data type. These contain, for example, currency values multiplied by a factor of one million (1,000,000).

Example: A value of EUR 123.4567 is output in the field as 123456700.

API Reports

We currently offer four different reports that can be retrieved in a customized format via the API.

Account Performance Report (Advertiser) Documentation

Ad Performance Report (Advertiser) Documentation

Campaign Performance Report (Advertiser) Documentation

Direct Placement Performance Report (Advertiser) Documentation

Placement Layout Performance Report (Publisher) Documentation

Site Performance Report (Publisher) Documentation

Further scopes and routes

Have you selected other scopes in your API access in addition to Reporting? To obtain the appropriate routes and information, please contact your AdUp representative or email us via support(at)adup-tech.com​​​​​​​.