Sovrn External API Documentation

Last Updated July 9, 2019

The instructions contained within this article will help you setup an external API for reporting purposes.

Generating your Access Token

You will need to get started with generating your access token. All requests to the Sovrn API will require the access token.

Making a request to get your access token is shown below:

  • The 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:

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. We’ve shared an example below:

Example Report Requests: Earnings, Key Metrics, & Ad Tags

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

The following are examples of API requests that you can create.

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}

To get an ‘overview’ of cpm, earnings, fill, impressions, requests by day for all sites:

  • GET request to
    • https://api.sovrn.com/overview/all?iid={00000000}&site=All%20Traffic&startDate={1552435200000}&endDate={1555027199999}&currency=USD
  • This will return an object –> cpm/ earnings/ fill/ impressions/ requests –> graphYou –> ‘date:{day}, amount:{amount}’
  • i.e. impressions.graphYou[#] = amount of impressions by day

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

&Parameters

The parameters included below can be used to further optimize what data you’re seeing from your API requests.

  • startDate and endDate:
    • timestamp in milliseconds of UTC of the day you want (e.g 12/01/2018 @ 12:00am (UTC) is represented by 1543622400)
    • be sure to specify the start and end of your date range
    • 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
  • 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:

If you need additional help with your API development, don’t hesitate to reach out to Sovrn Publisher Support.

How satisfied are you with this article?

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