Overview

The System1 Reporting API provides access to data in your account. This document intends to provide specifications of the API endpoints responsible for returning reporting data to you and our other partners. All endpoints require authentication in addition to any otherwise optional parameters listed.

Authentication

All System1 partners can use our API by requesting access from your Account Manager. When you ask for access you will receive an email from your Account Manager which includes your auth_key. This is the authentication key that will provide you and your team to access the below listed reporting API endpoints.

All requests to the reporting API use GET requests. These GET requests can include optional query parameters, and must include an authentication parameter for every request.

Let's start with an example and say that your authentication key is "test_06IDAJuUjUKgsdd". If you want to make an API request for the same data listed in the "31 Day Summary" sheet in your campaign report spreadsheet, you would simply make a GET request to:

https://reports.openmail.com/v1/summary.json?auth_key=test_06IDAJuUjUKgsdd

Similarly for the "31 Day By Campaign" report

https://reports.openmail.com/v1/campaign.json?auth_key=test_06IDAJuUjUKgsdd

and "14 Day by Campaign Subid" report:

https://reports.openmail.com/v1/subid.json?auth_key=test_06IDAJuUjUKgsdd

The reporting data status call is also the same:

https://reports.openmail.com/v1/status.json?auth_key=test_06IDAJuUjUKgsdd

When providing additional parameters to any of these endpoints, the order of query parameters does not matter.

Data availability, reliability, and historical data

Data Availability

System1 will expose any reporting data available from February 1, 2015 onwards. Reporting data for a given day will become available at 9AM PST but could be delayed up to five (5) days due to limitations in availability of upstream data from our third party advertising partners' platforms and our hosting provider uptime.

Rate limits

Due to the amount of data, System1 has a rate limit for each individual API call, and on the API as a whole. These limits are intentionally conservative, as the default options will return all available data from the existing email and FTPS reports. Abuse of the APIs may result in your account being temporarily or permanently banned.

Upon hitting the rate limit, you will receive a 429 error that will include a Retry-After header, which provides how many seconds you need to wait to make another valid request. In the below output example, the caller should wait at least 17 seconds to be able to make another request without running into the rate limit again:

HTTP/1.0 429 TOO MANY REQUESTS
Retry-After: 17
Content-Type: application/json
Content-Length: 2
Date: Fri, 04 Dec 2015 00:06:40 GMT
Server: nginx
Connection: keep-alive

In summary:

| Description ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Data Timezone | All data is in Coordinated Universal Time (UTC) Data Update Cadence | Daily but could be delayed by up to (3) days due to upstream partner data availability and our hosting provider uptime API Rate Limits | Accessing our API at 1 requests/second, 60 requests/minute and 240/hour should allow partners to keep within our rate limits and allow you to pull: 1. 5 months subid-level data in 10 second OR 2. 10 months of campaign and summary level data in 10 seconds

Getting Started

Check Data Status

In order to generate complete and correct reporting for any given day, System1 must fetch reporting data from our upstream partners/providers. For this reason, to ensure complete and correct reports, System1 will only make reporting data available after we have received the complete and correct data for any given day, and rarely this may mean delaying reporting to our partners. Periodic calls to the /v1/status.json endpoint will offer the most recently updated status report on data availability.

Suggested sequence for requesting updated data on a daily basis:

You make repeated calls to /v1/status.json separated by 5 minute intervals starting at 6AM Pacific time.
When the API response indicates that data is available for the dates you seek, you make API call(s) to whichever subset of the reporting data that you need.
You ingest the data into your data warehouse per your business logic.
All data returned is in JSON format, which can be parsed with built-in or 3rd party libraries available almost anywhere.

The current version of APIs are not updated intraday, so partners should make the next call to /v1/status.json the next calendar day at 6AM Pacific time.

Suggested API Usage

1. Check Status Example

Returns a JSON array of dates where System1 has complete reporting information. Dates that do not show up in this API call will not have any data returned by any of the other API calls. For example, you can include the days parameter in your request and dictate how many days of data you would like. The days parameters is optional and if not provided will return 31 days of data. Additionally, you can specify the number of days you would like returned (e.g. days = 10) or you can request specific days (e.g. days=2015-10-15,2015-10-13).

Parameters

The summary report only has one (1) specifiable parameter, days.

Parameter Name	Parameter Function
days(optional)	This parameter allows you to specify the number of days you'd like to get data for or specify specific days that you would like data for. If you omit this parameter it will return the full 31 days.

Example

Input:

$ curl "https://reports.openmail.com/v1/status.json?auth_key=test_06IDAJuUjUKgsdd&days=3"

Output:

["2015-11-30","2015-11-29","2015-11-28"]

The above example returns the last 3 days of complete data.

2. 31 Day Summary Report Example

Returns a JSON array of arrays, each sub-array representing a column from the '31 Day Summary' sheet from the existing campaign report. The first array returned defines the fields used in the subsequent arrays. Parameters

The summary report only has one (1) specifiable parameter, days.

Parameters

Parameter Name	Parameter Function
days(optional)	This parameter allows you to specify the number of days you'd like to get data for or specify specific days that you would like data for. If you omit this parameter it will return the full 31 days.

Example

Input:

$ curl "https://reports.openmail.com/v1/summary.json?auth_key=test_06IDAJuUjUKgsdd&days=3"

Output:

[["Date","Total Sessions","Mobile Sessions","Desktop Sessions","Mobile Sessions
%","Distinct IPs","Distinct Mobile IPs","Distinct Desktop IPs","Distinct Mobile
IPs %","Searches","Clicks","Estimated Gross Revenue","Ad Network
Adjustment","Estimated Net Revenue","Revenue Per Session","Revenue Per
Search","Revenue Per IP","Revenue Per Click","Clicks Per Session %"],["2015-12-0
8",15834,4477,11356,28.27,12021,3430,8591,28.53,16907,524,288.45,2.88,285.56,0.0
2,0.02,0.02,0.55,3.31],["2015-12-07",217559,61523,156036,28.28,165173,47131,1180
41,28.53,232307,7201,31895.98,318.96,31577.02,0.15,0.14,0.19,4.43,3.31],["2015-1
2-06",201890,57092,144797,28.28,153276,4377,109539,28.53,215575,6683,8438.28,84
.38,8353.9,0.04,0.04,0.06,1.26,3.31]]

The above example returns the last 3 days of complete data.

3. 31 Day By Campaign Summary Report Example

Returns a JSON array of arrays, each sub-array representing a column from the '31 Day By Campaign' sheet from the existing campaign report. The first array returned defines the fields used in the subsequent arrays.

Parameters

The 31 Day by Campaign Summary report has two (2) specifiable parameters, days and campaign.

Parameter Name	Parameter Function
days(optional)	This parameter allows you to specify the number of days you'd like to get data for or specify specific days that you would like data for. If you omit this parameter it will return the full 31 days.

Examples

Input:

$ curl "https://reports.openmail.com/v1/campaign.json?auth_key=test_06IDAJuUjUKgsdd&days=7"

Output:

[["Date","Campaign Domain","Total Sessions","Mobile Sessions","Desktop
Sessions","Mobile Sessions %","Distinct IPs","Distinct Mobile IPs","Distinct
Desktop IPs","Distinct Mobile IPs %","Searches","Clicks","Estimated Gross
Revenue","Revenue Per Session","Revenue Per Search","Revenue Per IP","Revenue
Per Click","Clicks Per Session %"],["2015-12-08","openmail.com",15834,4477,11356
,28.27,12021,3430,8591,28.53,16907,524,288.45,0.02,0.02,0.02,0.55,3.31],["2015-1
2-07","openmail.com",217559,61523,156036,28.28,165173,47131,118041,28.53,232307,
7201,31895.98,0.15,0.14,0.19,4.43,3.31],["2015-12-06","openmail.com",201890,5709
2,144797,28.28,153276,43737,109539,28.53,215575,6683,8438.28,0.04,0.04,0.06,1.26
,3.31],["2015-12-05","openmail.com",11491,3249,8241,28.27,8724,2489,6234,28.53,1
2269,380,837.1,0.07,0.07,0.1,2.2,3.31],["2015-12-04","openmail.com",644322,18220
7,462115,28.28,489174,139585,349589,28.53,687999,21328,24539.44,0.04,0.04,0.05,1
.15,3.31],["2015-12-03","openmail.com",114580,32402,82178,28.28,86990,24822,6216
7,28.53,122347,3792,2036.99,0.02,0.02,0.02,0.54,3.31],["2015-12-02","openmail.co
m",718986,203321,515665,28.28,545860,155760,390099,28.53,767724,23800,94094.46,0
.13,0.12,0.17,3.95,3.31]]

The above example returns the last 7 days of complete data.

Input:

$ curl "https://reports.openmail.com/v1/campaign.json?auth_key=test_06IDAJuUjUKgsdd&days=7&campaign=openmail.com"

Output:

[["Date","Campaign Domain","Total Sessions","Mobile Sessions","Desktop
Sessions","Mobile Sessions %","Distinct IPs","Distinct Mobile IPs","Distinct
Desktop IPs","Distinct Mobile IPs %","Searches","Clicks","Estimated Gross
Revenue","Revenue Per Session","Revenue Per Search","Revenue Per IP","Revenue
Per Click","Clicks Per Session %"],["2015-12-08","openmail.com",15834,4477,11356
,28.27,12021,3430,8591,28.53,16907,524,288.45,0.02,0.02,0.02,0.55,3.31],["2015-1
2-07","openmail.com",217559,61523,156036,28.28,165173,47131,118041,28.53,232307,
7201,31895.98,0.15,0.14,0.19,4.43,3.31],["2015-12-06","openmail.com",201890,5709
2,144797,28.28,153276,43737,109539,28.53,215575,6683,8438.28,0.04,0.04,0.06,1.26
,3.31],["2015-12-05","openmail.com",11491,3249,8241,28.27,8724,2489,6234,28.53,1
2269,380,837.1,0.07,0.07,0.1,2.2,3.31],["2015-12-04","openmail.com",644322,18220
7,462115,28.28,489174,139585,349589,28.53,687999,21328,24539.44,0.04,0.04,0.05,1
.15,3.31],["2015-12-03","openmail.com",114580,32402,82178,28.28,86990,24822,6216
7,28.53,122347,3792,2036.99,0.02,0.02,0.02,0.54,3.31],["2015-12-02","openmail.co
m",718986,203321,515665,28.28,545860,155760,390099,28.53,767724,23800,94094.46,0
.13,0.12,0.17,3.95,3.31]]`

The above example returns the last 7 days of complete data for campaign "openmail.com".

4. Campaign SubID Summary Report Example

Returns a JSON array of arrays, each sub-array representing a column from the '14 day by Campaign Subid' sheet from the existing campaign report. The first array returned defines the fields used in the subsequent arrays. Parameters The 31 Day by Campaign Summary report has three (3) specifiable parameters, days and campaign, and subid.

Parameter Name

Parameter Name	Parameter Function
days(optional)	This parameter allows you to specify the number of days you'd like to get data for or specify specific days that you would like data for. If you omit this parameter it will return the full 31 days.

Examples:

days=10 - get the most recent 10 days, the latest being yesterday UTC

days=2015-10-15,2015-10-13 - get the 2 dates of data specified

days=2015-10-15,2015-10-14,2015-10-13 - get the 3 dates of data specified

campaign(optional) | This parameter allows you to specify the campaigns you would like data for. If you include this parameter, this should be a comma-separated list of campaign to return data for. If omitted, it will return data for all campaigns with activity on the requested days.

Examples:

campaign=openmail.com - get the details for the provided campaign

campaign=openmail.com,othercampaign.com - get the details for the two specified campaigns

subid(optional) | This parameter allows you to specify the subids you would like data for. If you include this parameter, this should be a comma-separated list of subids to return data for. If omitted, it will return data for all campaign/subid pairs with activity on the requested days.

Examples:

subid=0 - get the details for the provided subid

subid=0,13_1556,11_1291 - get the details for the two provided subids

Example

Input:

$ curl "https://reports.openmail.com/v1/subid.json?auth_key=test_06IDAJuUjUKgsdd&days=10&subid=0"

Output:

[["Date","Campaign Domain","Sub ID","Total Sessions","Mobile Sessions","Desktop
Sessions","Mobile Sessions %","Distinct IPs","Distinct Mobile IPs","Distinct
Desktop IPs","Distinct Mobile IPs %","Searches","Clicks","Estimated Gross
Revenue","Revenue Per Session","Revenue Per Search","Revenue Per IP","Revenue
Per Click","Clicks Per Session %"],["2015-12-08","openmail.com","0",15834,4477,1
1356,28.27,12021,3430,8591,28.53,16907,524,288.45,0.02,0.02,0.02,0.55,3.31],["20
15-12-07","openmail.com","0",217559,61523,156036,28.28,165173,47131,118041,28.53
,232307,7201,31895.98,0.15,0.14,0.19,4.43,3.31],["2015-12-06","openmail.com","0"
,201890,57092,144797,28.28,153276,43737,109539,28.53,215575,6683,8438.28,0.04,0.
04,0.06,1.26,3.31],["2015-12-05","openmail.com","0",11491,3249,8241,28.27,8724,2
489,6234,28.53,12269,380,837.1,0.07,0.07,0.1,2.2,3.31],["2015-12-04","openmail.c
om","0",644322,182207,462115,28.28,489174,139585,349589,28.53,687999,21328,24539
.44,0.04,0.04,0.05,1.15,3.31],["2015-12-03","openmail.com","0",114580,32402,8217
8,28.28,86990,24822,62167,28.53,122347,3792,2036.99,0.02,0.02,0.02,0.54,3.31],["
2015-12-02","openmail.com","0",718986,203321,515665,28.28,545860,155760,390099,2
8.53,767724,23800,94094.46,0.13,0.12,0.17,3.95,3.31],["2015-12-01","openmail.com
","0",642892,181802,461090,28.28,488089,139275,348813,28.53,686472,21281,91444.6
4,0.14,0.13,0.19,4.3,3.31],["2015-11-30","openmail.com","0",17154,4850,12303,28.
27,13023,3716,9307,28.53,18316,567,989.82,0.06,0.05,0.08,1.75,3.31],["2015-11-29
","openmail.com","0",53496,15128,38368,28.28,40614,11589,29025,28.53,57122,1770,
3243.86,0.06,0.06,0.08,1.83,3.31]]

The above example returns the last 10 days of complete data for subid "0".

Security and Confidentiality

The authentication key provided to you by System1 currently offers the ability to obtain reporting data and reporting status. This data is considered by System1 to be confidential information to be shared only with System1 and the partner the reporting data applies to. System1 uses the authentication key to ensure that reporting data is only provided to those who should have access to the reporting data. As such, it is the partner's responsibility to ensure the confidentiality of the reported data and the authentication key that System1 provides.

If a partner has reason to believe that unauthorized people or systems have access to the authentication key, they need to report that to System1 ASAP. System1 will then disable that authentication key and supply a replacement to be used by the partner. Repeated failures to prevent public exposure of the API key will be cause to terminate the partner's access to the reporting API.