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

Prerequisites

To be able to use the AdUp API, create access for yourself. To do this, go to Profile in your account or read about it in more detail 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 access the Reports route using the access token. Have a look at the interactive documentation for this.

Step 4

Next, set up your personal API requests. You can find code examples, a description 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 at hand.

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'

Parameters:

Parameters:

Parameters:

• 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 resources of the API 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 received token 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 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 must 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 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 show any values in the metrics. This can be caused by non-deliverable items or items paused within the queried time period.

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

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

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 that have been 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 in a customised manner 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

Other Scopes and Routes

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