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 use the AdUp API, you need to create an API access. You can do this in your account under Profile, or read more in our 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

Use the Access Token to call the Reports Route. Check out the interactive documentation for this.

Step 4

Then, set up your personal API requests. Below in this article, you will find code examples, the description of all fields, as well as hints and links to all possible reports. 

Authentication & Access Token

Step 1: Obtain API login details

Make sure you have your API login details ready.

Step 2: Request 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 Access Token

After successful authentication, you will receive a response containing 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 runtime and must be renewed regularly.

• Responses are sent in JSON format. Further information: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept

• The usage 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 have to filter by device type.

In this case, you will want to segment your report by DeviceType. For example, if you add the Device field to a Campaign Performance Report, you will check a report with a row for each campaign and device type combination and the statistical values (impressions, clicks, conversions, etc.) split between 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 can contain rows that display no values under metrics. This can be caused by non-deliverable items or items paused within the queried time period.

To get 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 settings of the account.

To reduce the number of rows if there are many items without metrics, includeZeroImpressions should be set to false. Alternatively, a filter on metrics in conditions can also be used.

Date ranges

For each date_range_type except 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 as 123456700 in the field.

API Reports

We currently offer four different reports that can be retrieved individually 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 further scopes in addition to reporting in your API access? To get the suitable routes and information, please contact your AdUp contact person or write to us via support(at)adup-tech.com​​​​​​​.