Sovrn External API Documentation

Last Updated January 8, 2019

Getting Started:
Access Token
All requests to the Sovrn API will require the access token
⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼
Making a request to get your access token is shown below:

  • client_id and client_secret should be “sovrn”

sovrn-api-request-call

POST : https://api.sovrn.com/oauth/token

Include the information in your API request with your values in the body of POST request

The response body will contain your access token:

{
“access_token”: “1a9e432e-XXXX-4e8c-8985-2615f988c6d8”,
“token_type”: “bearer”,
“expires_in”: 1295999,
“scope”: “read/write”
}

A new access token value will be generated every time you make that POST request so be sure to use your most recent one.

Include your access token in requests to the Sovrn API in the header as a key-value:

Authorization: Bearer {ACCESS_TOKEN}

⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼

Retrieving your user IID

The IID is required to return data from all of the endpoints.
⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼
Making a request to get your IID:

GET : https://api.sovrn.com/account/user

sovrn-api-request-IID

include Authorization: Bearer {ACCESS_TOKEN} as your key-values in the GET request’s header

This will return a data-rich JSON object which includes your “iid” as an integer:

{
… ,
“iid”: 12345678,

}

⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼

Useful Endpoints:

Be sure to include Authorization: Bearer {ACCESS_TOKEN} as your key-values in the GET request’s header.
⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼
Earnings

For a specific site:

GET : https://api.sovrn.com/earnings/breakout/all?site={SITE.DOMAIN}&startDate={START_TIMESTAMP_MILLIS}&endDate={START_TIMESTAMP_MILLIS}&iid={IID}

For all traffic:

GET : https://api.sovrn.com/earnings/breakout/all?site=All%20Traffic&startDate={START_TIMESTAMP_MILLIS}&endDate={START_TIMESTAMP_MILLIS}&iid={IID}
⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼
Key Metrics

For a specific site:
GET :
https://api.sovrn.com/keymetrics?iid={IID}&site={SITE.DOMAIN}&startDate={START_TIMESTAMP_MILLIS}&endDate={START_TIMESTAMP_MILLIS}

For all traffic:

GET :
https://api.sovrn.com/keymetrics?iid={IID}&site=All%20Traffic&startDate={START_TIMESTAMP_MILLIS}&endDate={START_TIMESTAMP_MILLIS}
⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼
Ad Tags

Basic data for individual Ad Tag:

GET : https://api.sovrn.com/adtags/zone/{TAGID}/?iid={IID}

Basic data for all Ad Tags:

GET : https://api.sovrn.com/adtags/user?iid={IID}

⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼

&Parameters

startDate, endDate:

timestamp in milliseconds of UTC of the day you want (e.g 12/01/2018 @ 12:00am (UTC) is represented by 1543622400)

take into consideration:

  • data returned is in Mountain Standard Time but timestamp params must be in UTC so be sure to compensate for the +7hr UTC has over MST
  • for granular reporting, break out reports by day rather than in bulk

site:

by site:

  • all requests and metrics for the given approved site
  • site must exactly match approved domain name (e.g. domain.name)

all traffic:

  • all requests and metrics sent to Sovrn
  • ALL%20Traffic

currency:

  • currency abbreviation (e.g USD)

country:

  • country abbreviation (e.g US)

⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼⎼

Additional Helpful Resources:
Timestamp converter
Postman: Tool for API Development

How satisfied are you with this article?

  • Not at all satisfied
  • 1
  • 2
  • 3
  • 4
  • 5
  • Completely satisfied