Revision History

VersionDateNote
3.0.22017-01-26Initial version
5.0.02017-04-28

• Fix 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
• Add endpoint to “Creating line item” section
• All URLs are absolute
• change group name to “demand-partner” in /self/ response

5.1.02017-05-18

• Line items cannot be deleted but archived
• Better performance for filters in SDX API
• Endpoints’s name property is removed

Introduction

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

Please note that reporting data cannot be requested through the SDX API at this point.

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 according API tokens. Here’s how:

PLEASE NOTE: Never hand your API credentials (Client ID & Client Secret) to a third party!

This would compromise the security of your account.


  1. Go to https://auth.smaato.com/v2/auth/applications/ - here you’ll see all your authorized applications. On first use, this list should be blank, as per below:


  2. Click on New Application - You’ll be shown the following:

    Add a name to identify the application you’re authorizing - we recommend to use something specific (e.g. “Adrian Postman” or “Dashboard Cron Job”) instead of something generic like “App1”, “App2” etc.


  3. Click Save - your application will then be registered:


  4. All that’s left to do now is generate an access token; you can either click on Generate
    Token or request the token via API directly (next step):

    Clicking on Generate Token shows you a list of all tokens currently in use, and when they’ll 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/

Here’s an example response:

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

Getting Started & Example Requests/Responses

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

(warning) Please note that all parameters are case sensitive. 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”: “demo@smaato.com”,
“groups”: [
“demand-partner”
],
“status”: “ACTIVE”,
“association”: {
“type”: “DEMAND_PARTNER”,
“entity_id”: 1000001 // YOUR_DEMAND_PARTNER_ID
}
}

The Demand Partner ID is parameter for entity_id in the association object - in this example, the Demand Partner ID is 1000001. You’ll need the Demand Partner ID for all demand partner related API requests.

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.

Device Id Targeting

Option 1: File Upload

For the File upload you need a text file that contains a line separated list of file ids. So each line contains one device ID.

We allow up to 100kb per file so you have to split up the file if it is larger then that. Multi upload of files is possible.

For uploading this file you have to use the following endpoint:

The filename can be any given string. You should attach the device id file to the body of your request.
If the Upload was successful you get back a JSON with the actual filename that was upload.

{

"filename": "string"
}

Errors

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