SDX API

Revision History

Version Date Note
3.0.2 2017-01-26
  • Initial version release
5.0.0 2017-04-28
  • Fixed URL for generating a token
  • Getting line items” moved to “Getting started”
  • id, data_center, domain targeting,
  • iab-category targeting are removed from the example
  • Added endpoint to “Creating line item” section
  • All URLs are absolute
  • Changed group name to “demand-partner” in /self/ response
5.1.0 2017-05-18
  • Line items cannot be deleted but archived
  • Better performance for filters in SDX API
  • Endpoints’s name property removed

Introduction

The SDX API allows demand partners to access and modify their exchange connection and configuration directly through an API.

Full API Specification

You can find the full API specification at: https://sdx-api-spec.smaato.com/

The API specification contains all the information available about endpoints and parameters, and lets you test calls on the fly to format them.

If you need more introduction on how to use the API and the spec please continue reading, otherwise head on over to SDX and get started.

Authentication

Before you can use the SDX API, you will need to generate API tokens. Here is how to do that:

Getting Started

First, go to https://auth.smaato.com/v2/auth/applications/– here you will see all your authorized applications. On first use, this list should be blank, as per below:

Click on New Application – You will be shown the following window.

  • Add a name to identify the application you are authorizing –
  • We recommend using something specific (i.e. “Flying Squares” or “Golf Run”), instead of something very generic like “App 1”, “App 2” etc.
Click Save – Your application will then be registered.

All that is left now is to generate an access token.

  • You can either click on Generate Token or you can proceed to the next step which requests the token via API directly.
  • Click on Generate Token and you a list of all tokens currently in use, and you can also see when they will expire.

To generate an access token via API, use the following POST:

POST https://auth.smaato.com/v2/auth/token/

client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
grant_type=client_credentials

Or, if you’re using cURL:

$ curl -X POST -d
“grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET” https://
auth.smaato.com/v2/auth/token/

Example Response

{
“access_token”:
“eUwcr8Wi07IYHMFk9ppa2lIV5OZB0G”,
“expires_in”: 36000,
“token_type”:
“Bearer”, “scope”:
“read”
}

Example Requests and Responses

As soon as you’re set up with authentication, you can start setting up requests.

Below, you can find example requests for some of the most common requests.

Getting Your Demand Partner ID

Request the https://sdx-api.smaato.com/self/ endpoint (cURL example below):

curl -X GET --header ‘Accept: application/json’ --header ‘Authorization: Bearer [YOUR_ACCESS_TOKEN]’
‘https://sdx-api.smaato.
com/self/’

The response will look something like this:

{
“id”: 200,
“email”: “[email protected]”,
“groups”: [
“demand-partner”
],
“status”: “ACTIVE”,
“association”: {
“type”: “DEMAND_PARTNER”,
“entity_id”: 1000001 // YOUR_DEMAND_PARTNER_ID
}
}

The Demand Partner ID is a parameter for entity_id in the association object – in this example, the Demand Partner ID is 1000001.

Getting Line Items

You can get your line items via a GET on https://sdx-api.smaato.com/demandpartners/ [YOUR_DEMAND_PARTNER_ID] /line- items/smx/:

cUR

curl -X GET --header ‘Accept: application/json’ --header ‘Authorization: Bearer [YOUR_ACCESS_TOKEN]’ ‘https://sdx-api.smaato. com/demand-partners/[YOUR_DEMAND_PARTNER_ID]/lineitems/smx/’

The response will look something like this:

[

{
“id”: 1,
“name”: “Smaato Default Exchange Line Item”,
“description”: “This Smaato Exchange Default Line Item was generated automatically to ensure that
your system is receiving traffic from Smaato.”,
“data_center”: null,
“status”: “ACTIVE”,
“capping”: {},
“targeting”: {}
}
]

Getting Line Item KPIs

To get performance KPIs for any Line Item(s), you can POST a request to https://sdx-api.smaato.com/demand-partners/ [YOUR_DE- MAND_PARTNER_ID] /line-items/smx/kpi/ with dates and the Line Item ID(s) for which you’d like KPIs:

curl -X POST --header ‘Content-Type: application/json’ --header ‘Accept: application/json’ --header

‘Authorization: Bearer [YOUR_ACCESS_TOKEN]’ -d ‘{
“start_date”: “2017-04-10”,
“end_date”: “2017-04-16”,
“lineitems”: [ // optional, leaving away returns KPIs
for all line items 193
]
}’ ‘https://sdx-api.smaato.com/demand-partners/[YOUR_DEMAND_PARTNER_ID]/line-items/smx/kpi/’

For more detail on this feature, head to the full API specification.

Using Inventory Discovery

If you’re interested in getting QPS and traffic information, you can POST your targeting preferences to /inventory/discovery  – here’s an example for All US Traffic that has Geo Data (you’ll receive ad requests per day for the past week):

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' -d '{
  "geo": {
    "is_geo_data_required": true,
    "countries": {
      "identifiers": [
        {
          "code": "US"
        }
      ],
      "is_whitelist": true
    }
  }
}' 'https://sdx-api.smaato.com/inventory/discovery/'

For more detail on this feature, head to the Full API Specification.

Errors

  • Errors are JSON objects in combination with an HTTP error code other than HTTP 2xx.
  • Error responses are descriptive of the error at hand.

Modified: July 15, 2019 at 11:37 am