{"info":{"_postman_id":"181052be-7ebc-4850-bb7e-c18d014cf6b0","name":"Appsumer Reporting API","description":"

The Appsumer Reporting API allows BI teams to streamline ad spend ingestion and rely on a single API instead of dozens.

Using Appsumer and its normalized mobile ad cost data API saves countless hours of implementation and maintenance, making UA more effortless than ever. Appsumer is integrated with 100+ advertising APIs, empowering engineering and data teams to focus on core business projects rather than implementing and maintaining every single API required by their UA team.

If you want to learn more, get in touch. If you're here to implement our API, read on!

Requirements

An Appsumer Reporting API token linked to an active Appsumer account.
An active Appsumer user account to be able to access links in this documentation suffixed with a 🔐.

Version

This documentation is for the Reporting API v1.3 and was last updated in October 2021. Other versions of the API are not supported anymore.

Limits

Rate

The API rate limit is set to 10 API calls per 15 minutes windows.
- Pagination calls will not consume your limit
\n
Rate limit windows reset at: minutes 00, 15, 30, 45 of every hour.

You can monitor your usage in real time by checking the API's response:

{\n  \"api\": {\n    \"version\": \"1.3\",\n    \"usage\": 0.7\n  }\n}\n\n

In this case, we're using 0.7 out of 1 of our allowed usage. You'll be throttled as soon as you make an API call after usage has reached 1:

400 Error. API limit reached, please pace calls\n\n

We recommend checking the usage for every call, and pace calls when getting closer to the limit, especially if you have several independent consumers (e.g., your BI and another system).

Parameters

Metrics and dimensions

For every call you're allowed:

20 fields
10 group_by

Date ranges

Using a date range is mandatory except for /reports/status. When doing so, ensure that your date range is of:

7 days max if you're requesting dynamic_dimension in your group_by;
31 days max if not.

Response codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Description
`200`	Request successful
`400`	Bad Request
`401`	Unauthorised
`500`	Internal Server Error

Base path

https://api.appsumer.io/{{version}} where {{version}} would be a value such as v1.3.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Requirements","slug":"requirements"},{"content":"Version","slug":"version"},{"content":"Limits","slug":"limits"},{"content":"Response codes","slug":"response-codes"},{"content":"Base path","slug":"base-path"}],"owner":"7626860","collectionId":"181052be-7ebc-4850-bb7e-c18d014cf6b0","publishedId":"SVzw6go1","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2023-01-05T11:09:09.000Z"},"item":[{"name":"Endpoints","item":[{"name":"/reports","item":[{"name":"Getting your data","id":"79512bc5-b324-4342-98c5-2a02f0610b82","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.appsumer.io/v1.3/reports?token={{token}}&since=20190601&until=20190607&fields=impressions,clicks&group_by=partner_name,partner_country&order_type=asc&order_by=impressions&limit=5","description":"

This is a basic API call to retrieve your data for 7 days, using some of the available parameters. Try it on your end!

The returned response contains 3 objects, api, request, response. You'll find your data array in the response object.

Pages

You can know how many pages are returned by checking the value of total_pages in response.

\n","urlObject":{"protocol":"https","path":["v1.3","reports"],"host":["api","appsumer","io"],"query":[{"description":{"content":"

Required : Yes
Type: string
Expects: API Key

\n","type":"text/plain"},"key":"token","value":"{{token}}"},{"description":{"content":"

Required : Yes
Type: string
Expects: Start date in the format YYYYMMDD

\n","type":"text/plain"},"key":"since","value":"20190601"},{"description":{"content":"

Required : Yes
Type: string
Expects: End date in the format YYYYMMDD

\n","type":"text/plain"},"key":"until","value":"20190607"},{"description":{"content":"

Required : No
Type: string
Expects: values from the available fields, comma separated

\n","type":"text/plain"},"key":"fields","value":"impressions,clicks"},{"description":{"content":"

Required : No
Type: string
Expects: values from the available group_by, comma separated

\n","type":"text/plain"},"key":"group_by","value":"partner_name,partner_country"},{"description":{"content":"

Required : No
Type: string
Expects: ASC or DESC

\n","type":"text/plain"},"key":"order_type","value":"asc"},{"description":{"content":"

Required : No
Type: string
Expects: value from the available fields, comma separated
Defaults to: orders by date and ad_id

\n","type":"text/plain"},"key":"order_by","value":"impressions"},{"description":{"content":"

Required : No
Type: int
Expects: fields from the available fields, comma separated
Defaults to: 10000

\n","type":"text/plain"},"key":"limit","value":"5"}],"variable":[]}},"response":[{"id":"50c48a60-035d-4ff7-9e13-f0b9993c5d61","name":"Getting your data","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.appsumer.io/v1.3/reports?token={{token}}&since=20190601&until=20190607&fields=impressions,clicks&group_by=partner_name,partner_country&order_type=asc&order_by=impressions&limit=5","protocol":"https","host":["api","appsumer","io"],"path":["v1.3","reports"],"query":[{"key":"token","value":"{{token}}","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** API Key"},{"key":"since","value":"20190601","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** Start date in the format YYYYMMDD"},{"key":"until","value":"20190607","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** End date in the format YYYYMMDD"},{"key":"fields","value":"impressions,clicks","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** values from the available `fields`, comma separated"},{"key":"group_by","value":"partner_name,partner_country","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** values from the available `group_by`, comma separated"},{"key":"order_type","value":"asc","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** ASC or DESC"},{"key":"order_by","value":"impressions","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** value from the available `fields`, comma separated"},{"key":"limit","value":"5","description":"- **Required :** `No`\n- **Type:** `int`\n- **Expects:** fields from the available fields, comma separated\n- **Defaults to:** `10000`"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 02 Jul 2019 20:40:19 GMT"},{"key":"Server","value":"Apache"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Accept-Ranges","value":"none"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Content-Encoding","value":"gzip"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Methods","value":"POST, GET, OPTIONS, DELETE, PUT"},{"key":"Access-Control-Allow-Methods","value":"GET"},{"key":"Access-Control-Max-Age","value":"1728000"},{"key":"Content-Length","value":"459"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Connection","value":"Keep-Alive"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\r\n \"api\": {\r\n \"version\": \"1.3\",\r\n \"usage\": 0.03\r\n },\r\n \"request\": {\r\n \"url\": \"https://api.appsumer.io/v1.3/reports?fields=impressions,clicks&group_by=partner_name,partner_country&limit=5&order_by=impressions&order_type=asc&since=20190601&token={{token}}&until=20190607\",\r\n \"date_time\": \"2019-11-25 15:28:39\"\r\n },\r\n \"response\": {\r\n \"date_time\": \"2019-11-25 15:28:39\",\r\n \"reporting_status\": \"Complete\",\r\n \"count_data\": true,\r\n \"current_page\": 1,\r\n \"total_pages\": 363,\r\n \"current_records\": 5,\r\n \"total_records\": 1814,\r\n \"data\": [\r\n {\r\n \"partner_name\": \"LiftOff\",\r\n \"partner_country\": \"ES\",\r\n \"impressions\": \"4000\",\r\n \"clicks\": \"151\"\r\n },\r\n {\r\n \"partner_name\": \"Unity Ads\",\r\n \"partner_country\": \"GB\",\r\n \"impressions\": \"365484\",\r\n \"clicks\": \"1321\"\r\n },\r\n {\r\n \"partner_name\": \"AdColony\",\r\n \"partner_country\": \"DE\",\r\n \"impressions\": \"151\",\r\n \"clicks\": \"1\"\r\n },\r\n {\r\n \"partner_name\": \"Lifestreet\",\r\n \"partner_country\": \"US\",\r\n \"impressions\": \"326889\",\r\n \"clicks\": \"3523\"\r\n },\r\n {\r\n \"partner_name\": \"LiftOff\",\r\n \"partner_country\": \"US\",\r\n \"impressions\": \"2516667\",\r\n \"clicks\": \"45370\"\r\n }\r\n ]\r\n }\r\n}"}],"_postman_id":"79512bc5-b324-4342-98c5-2a02f0610b82"},{"name":"Using parameters","id":"e6ea182c-648f-4809-8717-03c65b02704f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.appsumer.io/v1.3/reports?token={{token}}&since=20190601&until=20190607&fields=impressions,clicks&group_by=partner_name,partner_country&order_type=asc&order_by=impressions&limit=5&page=1¤cy=usd&format_data=false&decimal_places=2&hide_empty_rows=true&include_fees=false","description":"

This sample request uses all the available parameters. You can see each parameter's definition below (excluding filters, which have a dedicated section):

\n","urlObject":{"protocol":"https","path":["v1.3","reports"],"host":["api","appsumer","io"],"query":[{"description":{"content":"

Required : Yes
Type: string
Expects: API Key

\n","type":"text/plain"},"key":"token","value":"{{token}}"},{"description":{"content":"

Required : Yes
Type: string
Expects: Start date in the format YYYYMMDD

\n","type":"text/plain"},"key":"since","value":"20190601"},{"description":{"content":"

Required : Yes
Type: string
Expects: End date in the format YYYYMMDD

\n","type":"text/plain"},"key":"until","value":"20190607"},{"description":{"content":"

Required : No
Type: string
Expects: values from the available fields, comma separated

\n","type":"text/plain"},"key":"fields","value":"impressions,clicks"},{"description":{"content":"

Required : No
Type: string
Expects: values from the available group_by, comma separated

\n","type":"text/plain"},"key":"group_by","value":"partner_name,partner_country"},{"description":{"content":"

Required : No
Type: string
Expects: ASC or DESC

\n","type":"text/plain"},"key":"order_type","value":"asc"},{"description":{"content":"

Required : No
Type: string
Expects: value from the available fields, comma separated
Defaults to: orders by date and ad_id

\n","type":"text/plain"},"key":"order_by","value":"impressions"},{"description":{"content":"

Required : No
Type: int
Expects: The amount of results per page
Defaults to: 10000

\n","type":"text/plain"},"key":"limit","value":"5"},{"description":{"content":"

Required : No
Type: int
Expects: the page to get the data for

\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"

Required : No
Type: string
Defaults to: your account default currency
Expects: currency code (USD, EUR, GBP)

\n","type":"text/plain"},"key":"currency","value":"usd"},{"description":{"content":"

Required : No
Type: bool
Defaults to: false
Behavior: Adds a currency sign and currency format if true

\n","type":"text/plain"},"key":"format_data","value":"false"},{"description":{"content":"

Required : No
Type: int
Defaults to: 2, max 5

\n","type":"text/plain"},"key":"decimal_places","value":"2"},{"description":{"content":"

Required : No
Type: bool
Defaults to: false

\n","type":"text/plain"},"key":"hide_empty_rows","value":"true"},{"description":{"content":"

Required : No
Type: bool
Defaults to: false

\n","type":"text/plain"},"key":"include_fees","value":"false"}],"variable":[]}},"response":[{"id":"178bc758-c55f-48a9-b020-70df8a3c76a0","name":"Using parameters","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.appsumer.io/v1.3/reports?token={{token}}&since=20190601&until=20190607&fields=impressions,clicks&group_by=partner_name,partner_country&order_type=asc&order_by=impressions&limit=5&page=1&include_fees=false¤cy=usd&format_data=false&decimal_places=2&hide_empty_rows=true","protocol":"https","host":["api","appsumer","io"],"path":["v1.3","reports"],"query":[{"key":"token","value":"{{token}}","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** API Key"},{"key":"since","value":"20190601","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** Start date in the format YYYYMMDD"},{"key":"until","value":"20190607","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** End date in the format YYYYMMDD"},{"key":"fields","value":"impressions,clicks","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** values from the available `fields`, comma separated"},{"key":"group_by","value":"partner_name,partner_country","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** values from the available `group_by`, comma separated"},{"key":"order_type","value":"asc","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** ASC or DESC"},{"key":"order_by","value":"impressions","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** value from the available `fields`, comma separated"},{"key":"limit","value":"5","description":"- **Required :** `No`\n- **Type:** `int`\n- **Expects:** fields from the available fields, comma separated\n- **Defaults to:** `10000`"},{"key":"page","value":"1"},{"key":"include_fees","value":"false"},{"key":"currency","value":"usd"},{"key":"format_data","value":"false"},{"key":"decimal_places","value":"2"},{"key":"hide_empty_rows","value":"true"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 02 Jul 2019 20:40:19 GMT"},{"key":"Server","value":"Apache"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Accept-Ranges","value":"none"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Content-Encoding","value":"gzip"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Methods","value":"POST, GET, OPTIONS, DELETE, PUT"},{"key":"Access-Control-Allow-Methods","value":"GET"},{"key":"Access-Control-Max-Age","value":"1728000"},{"key":"Content-Length","value":"459"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Connection","value":"Keep-Alive"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\r\n \"api\": {\r\n \"version\": \"1.3\",\r\n \"usage\": 0\r\n },\r\n \"request\": {\r\n \"url\": \"https://api.appsumer.io/v1.3/reports?currency=usd&decimal_places=2&fields=impressions,clicks&format_data=false&group_by=partner_name,partner_country&hide_empty_rows=true&include_fees=false&limit=5&order_by=impressions&order_type=asc&page=1&since=20190601&token={{token}}&until=20190607\",\r\n \"date_time\": \"2019-11-25 15:26:51\"\r\n },\r\n \"response\": {\r\n \"date_time\": \"2019-11-25 15:26:51\",\r\n \"reporting_status\": \"Complete\",\r\n \"count_data\": true,\r\n \"current_page\": 1,\r\n \"total_pages\": 211,\r\n \"current_records\": 5,\r\n \"total_records\": 1051,\r\n \"data\": [\r\n {\r\n \"partner_name\": \"Facebook Ads\",\r\n \"partner_country\": \"NL\",\r\n \"impressions\": \"264421\",\r\n \"clicks\": \"1685\"\r\n },\r\n {\r\n \"partner_name\": \"Facebook Ads\",\r\n \"partner_country\": \"SE\",\r\n \"impressions\": \"326889\",\r\n \"clicks\": \"3523\"\r\n },\r\n {\r\n \"partner_name\": \"Facebook Ads\",\r\n \"partner_country\": \"US\",\r\n \"impressions\": \"583748\",\r\n \"clicks\": \"69411\"\r\n },\r\n {\r\n \"partner_name\": \"Facebook Ads\",\r\n \"partner_country\": \"DE\",\r\n \"impressions\": \"753266\",\r\n \"clicks\": \"13791\"\r\n },\r\n {\r\n \"partner_name\": \"Applovin\",\r\n \"partner_country\": \"US\",\r\n \"impressions\": \"2516667\",\r\n \"clicks\": \"45370\"\r\n }\r\n ]\r\n }\r\n}"}],"_postman_id":"e6ea182c-648f-4809-8717-03c65b02704f"},{"name":"Filtering your data","id":"03150e02-db15-437c-8025-6346f9804096","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.appsumer.io/v1.3/reports?token={{token}}&since=20190601&until=20190607&fields=impressions,clicks&group_by=partner_name,partner_country&limit=5&filter_type=include&filter[0][0][field]=partner_country&filter[0][0][operator]=equals&filter[0][0][value]=US&filter[0][1][field]=partner_name&filter[0][1][operator]=equals&filter[0][1][value]=Facebook","description":"

This example shows how to filter your data, using one of the available operators:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Operator	Description (Filters according to)
`equals`	Data matches given [string]
`not_equals`	Data does not match given [string]
`contains`	Data consists of [string]
`not_contains`	Data does not consist of [string]
`like`	Data consists of [string]
`not_like`	Data does not consist of [string]
`starts`	Data begins with [string]
`ends`	Data ends with [string]
`is_null`	Data value is `null`
`is_not_null`	Data value is not `null`
`has_value`	Data is not empty
`has_no_value`	Data is empty

You can OR or AND your filters by grouping them together. Filters of the same group are ANDed, and each different groups are ORed.

In the sample request, it's an AND: Facebook AND US. In order to change this to an OR, the request should have been made with 2 groups (filter[0] and filter[1]).

AND

Country = US AND partner_name = Facebook

filter[0][0][field]=\"country\"\nfilter[0][0][operator]=\"equals\"\nfilter[0][0][value]=\"US\"\nfilter[0][1][field]=\"partner_name\"\nfilter[0][1][operator]=\"equals\"\nfilter[0][1][value]=\"Facebook\"\n

OR

Country = US OR partner_name = Facebook

filter[0][0][field]=\"country\"\nfilter[0][0][operator]=\"equals\"\nfilter[0][0][value]=\"US\"\nfilter[1][0][field]=\"partner_name\"\nfilter[1][0][operator]=\"equals\"\nfilter[1][0][value]=\"Facebook\"\n

Combined

(Country = US AND OS = Android) OR partner_name = Facebook

filter[0][0][field]=\"country\"\nfilter[0][0][operator]=\"equals\"\nfilter[0][0][value]=\"US\"\nfilter[0][1][field]=\"os\"\nfilter[0][1][operator]=\"equals\"\nfilter[0][1][value]=\"Android\"\nfilter[1][0][field]=\"partner_name\"\nfilter[1][0][operator]=\"equals\"\nfilter[1][0][value]=\"Facebook\"\n

","urlObject":{"protocol":"https","path":["v1.3","reports"],"host":["api","appsumer","io"],"query":[{"description":{"content":"

Required : Yes
Type: string
Expects: API Key

\n","type":"text/plain"},"key":"token","value":"{{token}}"},{"description":{"content":"

Required : Yes
Type: string
Expects: Start date in the format YYYYMMDD

\n","type":"text/plain"},"key":"since","value":"20190601"},{"description":{"content":"

Required : Yes
Type: string
Expects: End date in the format YYYYMMDD

\n","type":"text/plain"},"key":"until","value":"20190607"},{"description":{"content":"

Required : No
Type: string
Expects: values from the available fields, comma separated

\n","type":"text/plain"},"key":"fields","value":"impressions,clicks"},{"description":{"content":"

Required : No
Type: string
Expects: values from the available group_by, comma separated

\n","type":"text/plain"},"key":"group_by","value":"partner_name,partner_country"},{"description":{"content":"

Required : No
Type: int
Expects: The amount of results per page
Defaults to: 10000

\n","type":"text/plain"},"key":"limit","value":"5"},{"description":{"content":"

Required : No
Type: string
Expects: include or exclude

\n","type":"text/plain"},"key":"filter_type","value":"include"},{"key":"filter[0][0][field]","value":"partner_country"},{"key":"filter[0][0][operator]","value":"equals"},{"description":{"content":"

Note : case insensitive. Filtering US or us will return the same data.

\n","type":"text/plain"},"key":"filter[0][0][value]","value":"US"},{"key":"filter[0][1][field]","value":"partner_name"},{"key":"filter[0][1][operator]","value":"equals"},{"key":"filter[0][1][value]","value":"Facebook"}],"variable":[]}},"response":[{"id":"44149ed1-3679-4a06-b959-ef8124b33bc0","name":"Filtering your data","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.appsumer.io/v1.3/reports?token={{token}}&since=20190601&until=20190607&fields=impressions,clicks&group_by=partner_name,partner_country&limit=500&filter_type=include&filter[0][0][field]=partner_country&filter[0][0][operator]=equals&filter[0][0][value]=US&filter[0][1][field]=partner_name&filter[0][1][operator]=equals&filter[0][1][value]=Facebook","protocol":"https","host":["api","appsumer","io"],"path":["v1.3","reports"],"query":[{"key":"token","value":"{{token}}","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** API Key"},{"key":"since","value":"20190601","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** Start date in the format YYYYMMDD"},{"key":"until","value":"20190607","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** End date in the format YYYYMMDD"},{"key":"fields","value":"impressions,clicks","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** values from the available `fields`, comma separated"},{"key":"group_by","value":"partner_name,partner_country","description":"- **Required :** `No`\n- **Type:** `string`\n- **Expects:** values from the available `group_by`, comma separated"},{"key":"limit","value":"500","description":"- **Required :** `No`\n- **Type:** `int`\n- **Expects:** fields from the available fields, comma separated\n- **Defaults to:** `10000`"},{"key":"filter_type","value":"include"},{"key":"filter[0][0][field]","value":"partner_country"},{"key":"filter[0][0][operator]","value":"equals"},{"key":"filter[0][0][value]","value":"US"},{"key":"filter[0][1][field]","value":"partner_name"},{"key":"filter[0][1][operator]","value":"equals"},{"key":"filter[0][1][value]","value":"Facebook"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 02 Jul 2019 20:40:19 GMT"},{"key":"Server","value":"Apache"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Accept-Ranges","value":"none"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Content-Encoding","value":"gzip"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Methods","value":"POST, GET, OPTIONS, DELETE, PUT"},{"key":"Access-Control-Allow-Methods","value":"GET"},{"key":"Access-Control-Max-Age","value":"1728000"},{"key":"Content-Length","value":"459"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Connection","value":"Keep-Alive"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"api\": {\n \"version\": \"1.3\",\n \"usage\": 0.1\n },\n \"request\": {\n \"url\": \"https://api.appsumer.io/v1.3/reports?fields=impressions,clicks&filter[0][0][field]=partner_country&filter[0][0][operator]=equals&filter[0][0][value]=US&filter[0][1][field]=partner_name&filter[0][1][operator]=equals&filter[0][1][value]=Facebook&filter_type=include&group_by=partner_name,partner_country&limit=500&since=20190601&token={{token}}&until=20190607\",\n \"date_time\": \"2019-11-25 13:46:03\"\n },\n \"response\": {\n \"date_time\": \"2019-11-25 13:46:03\",\n \"reporting_status\": \"Complete\",\n \"count_data\": true,\n \"current_page\": 0,\n \"total_pages\": 0,\n \"current_records\": 0,\n \"total_records\": 0,\n \"data\": [\n \t {\n \"partner_name\": \"Facebook\",\n \"partner_country\": \"US\",\n \"impressions\": \"6035914\",\n \"clicks\": \"49824\"\n }\t\n \t]\n }\n}"}],"_postman_id":"03150e02-db15-437c-8025-6346f9804096"},{"name":"Getting modified data only","id":"0c43142b-f488-4c46-aec9-8ddfd566bfe6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.appsumer.io/v1.3/reports?token={{token}}&since=20190601&until=20190607&fields=impressions,clicks&group_by=partner_name,partner_country&limit=5&modified=true","description":"

\n
💡 This feature is experimental — expect changes in the upcoming API versions.
\n

If you want to check if data you already have retrieved is still up to date, you can use the modified flag. When set to true, the API returns data for all of the ads having metrics for the period (since to until) that have been modified, at least one day after since.

It's important to note that this will include ALL records for ads that were modified, even if nothing was modified for a particular day.
These calls consume more resources on our end, and will take longer to return a response than calls not using the modified flag.

Calling the API between 2019-11-01 and 2019-11-10 with a group_by date will return data for all the selected dates, even if the ads were only modified on 2019-11-05.

By default, the API will break down results by ad_id on top of other group_by used.

\n","urlObject":{"protocol":"https","path":["v1.3","reports"],"host":["api","appsumer","io"],"query":[{"description":{"content":"

Required : Yes
Type: string
Expects: API Key

\n","type":"text/plain"},"key":"token","value":"{{token}}"},{"description":{"content":"

Required : Yes
Type: string
Expects: Start date in the format YYYYMMDD

\n","type":"text/plain"},"key":"since","value":"20190601"},{"description":{"content":"

Required : Yes
Type: string
Expects: End date in the format YYYYMMDD

\n","type":"text/plain"},"key":"until","value":"20190607"},{"description":{"content":"

Required : No
Type: string
Expects: values from the available fields, comma separated

\n","type":"text/plain"},"key":"fields","value":"impressions,clicks"},{"description":{"content":"

Required : No
Type: string
Expects: values from the available group_by, comma separated

\n","type":"text/plain"},"key":"group_by","value":"partner_name,partner_country"},{"key":"limit","value":"5"},{"description":{"content":"

Required : No
Type: bool

\n","type":"text/plain"},"key":"modified","value":"true"}],"variable":[]}},"response":[],"_postman_id":"0c43142b-f488-4c46-aec9-8ddfd566bfe6"}],"id":"13947cc3-aedc-413f-b081-425a63ca1700","description":"

Provides a single interface to retrieve the data from your Appsumer Account.

\n","event":[{"listen":"prerequest","script":{"id":"92180613-b195-4f30-8495-1bc3815c79d1","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"c0dcacea-5c7a-4ba5-a50d-e89ef0ef39eb","type":"text/javascript","exec":[""]}}],"_postman_id":"13947cc3-aedc-413f-b081-425a63ca1700"},{"name":"/reports/status","item":[{"name":"Checking your data status","id":"520b4e7b-a0bc-4e88-81fa-22f29b02fa3e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.appsumer.io/v1.3/reports/status?token={{token}}&since=20190619&until=20190620","urlObject":{"protocol":"https","path":["v1.3","reports","status"],"host":["api","appsumer","io"],"query":[{"description":{"content":"

Required : Yes
Type: string
Expects: API Key

\n","type":"text/plain"},"key":"token","value":"{{token}}"},{"description":{"content":"

Required : Yes
Type: string
Expects: Start date in the format YYYYMMDD

\n","type":"text/plain"},"key":"since","value":"20190619"},{"description":{"content":"

Required : Yes
Type: string
Expects: End date in the format YYYYMMDD

\n","type":"text/plain"},"key":"until","value":"20190620"}],"variable":[]}},"response":[{"id":"e255e81c-5cf4-4c8f-98b9-a61c28e6489c","name":"Getting you data status","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.appsumer.io/v1.3/reports/status?token={{token}}&since=2019-11-24&until=2019-11-24","protocol":"https","host":["api","appsumer","io"],"path":["v1.3","reports","status"],"query":[{"key":"token","value":"{{token}}","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** API Key"},{"key":"since","value":"2019-11-24","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** Start date in the format YYYYMMDD"},{"key":"until","value":"2019-11-24","description":"- **Required :** `Yes`\n- **Type:** `string`\n- **Expects:** End date in the format YYYYMMDD"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 02 Jul 2019 21:04:31 GMT"},{"key":"Server","value":"Apache"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Accept-Ranges","value":"none"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Content-Encoding","value":"gzip"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Methods","value":"POST, GET, OPTIONS, DELETE, PUT"},{"key":"Access-Control-Allow-Methods","value":"GET"},{"key":"Access-Control-Max-Age","value":"1728000"},{"key":"Content-Length","value":"235"},{"key":"Keep-Alive","value":"timeout=5, max=100"},{"key":"Connection","value":"Keep-Alive"},{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\r\n \"api\": {\r\n \"version\": \"1.3\",\r\n \"usage\": 0.5\r\n },\r\n \"request\": {\r\n \"date_time\": \"2019-11-25 13:42:44\",\r\n \"request_url\": \"https://api.appsumer.io/v1.3/reports/status?since=2019-11-24&token={{token}}&until=2019-11-24\"\r\n },\r\n \"response\": {\r\n \t\"status\": \"in_progress\",\r\n \t\"category\": {\r\n\t \"data_aggregation\": {\r\n\t \"status\": \"in_progress\",\r\n\t \"type\": {\r\n\t \"analytics\": {\r\n\t \"status\": \"in_progress\",\r\n\t \"source\": {\r\n\t \"Amplitude\": \"in_progress\"\r\n\t }\r\n\t },\r\n\t \"cost\": {\r\n\t \"status\": \"in_progress\",\r\n\t \"source\": {\r\n\t \"Facebook Ads\": \"complete\",\r\n\t \"Google Ads\": \"queued\"\r\n\t }\r\n\t }\r\n\t }\r\n\t },\r\n\t \"data_enrichment\": {\r\n\t \"status\": \"in_progress\",\r\n\t \"type\": {\r\n\t \"tags\": {\r\n\t \"status\": \"in_progress\",\r\n\t \"source\": {\r\n\t \"Appsumer\": \"in_progress\"\r\n\t }\r\n\t }\r\n\t }\r\n\t }\r\n \t}\r\n }\r\n}"}],"_postman_id":"520b4e7b-a0bc-4e88-81fa-22f29b02fa3e"}],"id":"1eefdd33-725c-4673-9778-9ac4b83205e5","description":"

Provides an interface to retrieve the status of your data aggregation and enrichment tasks for the previous day. It is advised checking the response of /reports/status before calling /reports in order to ensure we've processed all your scheduled data tasks successfully before pulling the data.

/reports/status returns the same info as the Data Status feature of the platform

Possible values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Description
Queued	Not started
In Progress	Currently in progress
Incomplete	Some or all the underlying Tasks have failed
Complete	All the underlying Tasks have completed
Enhanced	Data enhancement has been verified

To better understand Data Status and ensure you trigger your API calls at the right time, please read:

Data Status 🔐
API Best Practices 🔐

\n","event":[{"listen":"prerequest","script":{"id":"19999be5-3926-4d38-a217-9cd26441244a","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"6e7babda-da97-4b36-bc8c-2b5de5831814","type":"text/javascript","exec":[""]}}],"_postman_id":"1eefdd33-725c-4673-9778-9ac4b83205e5"}],"id":"9f91e375-3604-47a8-9422-a9b76536f9e7","_postman_id":"9f91e375-3604-47a8-9422-a9b76536f9e7","description":""},{"name":"Fields reference","item":[],"id":"395f7356-f83a-4f1b-bb6e-65771046b948","description":"

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

API Field	Metric group	Label	Description
`partner_spend`	Performance	Spend	Media spend value in the set `currency`, or in the advertiser default currency if `currency` is not specified. This spend amount includes fees if `include_fees` is set to `true`.
`publisher_spend_local`	Performance	Publisher Spend (Local)	Media spend value exactly as ingested from the partner, in partner currency.
`publisher_spend_advertiser`	Performance	Publisher Spend (Advertiser)	Media spend value exactly as ingested from the partner, in advertiser default currency.
`impressions`	Performance	Impressions	Impression count.
`video_views`	Performance	Video Views	Video view count.
`clicks`	Performance	Clicks	Click count.
`installs`	Performance	Installs	Install count.
`custom_performance_event_{one→five}`	Performance	Custom label	Metric count. You may have up to 5 custom performance metrics configured.
`activated_app`	Conversion	Activated App	Metric count.
`added_payment_info`	Conversion	Added Payment Info	Metric count.
`completed_registration`	Conversion	Completed Registration	Metric count.
`completed_tutorial`	Conversion	Completed Tutorial	Metric count.
`rated`	Conversion	Rated	Metric count.
`launch`	Conversion	Launch	Metric count.
`achieved_level`	Conversion	Achieved Level	Metric count.
`search`	Conversion	Search	Metric count.
`unlocked_achievement`	Conversion	Unlocked Achievement	Metric count.
`viewed_content`	Conversion	Viewed Content	Metric count.
`added_to_cart`	Conversion	Added to Cart	Metric count.
`revenue_added_to_cart`	Conversion	Revenue per Added to Cart	Metric value (monetary).
`added_to_wishlist`	Conversion	Added to Wishlist	Metric count.
`revenue_added_to_wishlist`	Conversion	Revenue (Added to Wishlist)	Metric value (monetary).
`initiated_checkout`	Conversion	Initiated Checkout	Metric count.
`revenue_initiated_checkout`	Conversion	Revenue per Initiated Checkout	Metric value (monetary).
`purchase`	Conversion	Purchase	Metric count.
`revenue_purchase`	Conversion	Revenue per Purchase	Metric value (monetary).
`spent_credits`	Conversion	Spent Credits	Metric count.
`revenue_spent_credits`	Conversion	Revenue per Spent Credits	Metric value (monetary).

`custom_event_{one→five}`	Conversion	Custom label	Metric count. You may have up to 5 custom events configured.
`revenue_custom_event_{one→five}`	Conversion	Custom label	Metric value (monetary). You may have up to 5 custom events configured.
`retention`	Conversion	Retained Users	Metric count.

Activity data for performance metrics

Simply request the field you need, as shown in the table. For instance, for clicks, request clicks.

Activity data for conversion metrics

If your account uses activity-enabled conversion metrics, you can retrieve their related data using the _act modifier. For instance, use added_to_cart_act to retrieve any activity data for the added_to_cart metric.

Cohort data for conversion metrics

For each conversion metric listed in the table above, you can specify a specific period window to retrieve. For day periods, use the _dse_{period} modifier, and for month period, use _mse_{period} where periods are:

first: first period window
second: second period window
third: third period window
fourth: fourth period window
fifth: fifth period window

For instance, to retrieve your day 7 revenue, you'd use revenue_purchase_dse_second if your account is configured with the second period set to day 7.

If you want to retrieve your month 3 period, you'd use revenue_purchase_mse_third if your account is configured with the third period set to month 3.

These periods are set in your account, and if you're unsure of what they are, you can reach out to support@appsumer.io to get the list.

\n","event":[{"listen":"prerequest","script":{"id":"3e488ff3-98cd-42e0-9f91-1fd076e1b24d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5477d22e-076d-4f85-9012-a8c76211fcdb","type":"text/javascript","exec":[""]}}],"_postman_id":"395f7356-f83a-4f1b-bb6e-65771046b948"},{"name":"Dimensions reference","item":[],"id":"1f7e21b6-c265-45ff-8473-1cb31337b54f","description":"

Primary dimensions

These are the most important dimensions for automating the ingestion of cost and/or attribution data from Appsumer.

Dimension	Label	Description (default behavior)
`ad_id`	Ad ID	Unique Tag id. Identifies a unique combination of dimensions. This is not the `partner_ad_id`.
`third_party_reference`	Unique reference	Defined on the fly, this reference is unique to each Tag.
`date`	Date	Activity date.
`partner_account_id`	Partner Account ID	Ad account id as available partner side.
`partner_account_name`	Partner Account Name	Ad account name as available partner side.
`partner_ad_id`	Partner Ad ID	Ad id as available partner side.
`partner_ad_name`	Partner Ad Name	Ad name as available partner side.
`partner_adgroup_id`	Partner Ad Group ID	Ad group id as available partner side.
`partner_adgroup_name`	Partner Ad Group	Ad group name as available partner side.
`partner_campaign_id`	Partner Campaign ID	Campaign id as available partner side.
`partner_campaign_name`	Partner Campaign Name	Campaign name as available partner side.
`partner_name`	Partner	Media partner name.
`app_name`	App	The app that you will be sending the users to.
`channel_name`	Channel	Channel describes the primary channel in which the ad is going to be promoted.
`country_name`	Country	Country as set on your account (can be either Targeted or Delivered).
`destination_name`	Destination	Landing page name.
`device_name`	Device	Device name.
`os_name`	OS	OS.
`dimension_one`	Dimension One	Custom dimension.
`dimension_three`	Dimension Three	Custom dimension.
`dimension_two`	Dimension Two	Custom dimension.
`dynamic_dimension`	Dynamic Dimension	Special dimension that can hold source-specific breakdowns.

Secondary dimensions

These dimensions may be useful for specific use cases.

Dimension	Label	Description (default behavior)
`week_number`	Week	Week of the year.
`year`	Year	Year in `YYYY` format e.g. `2019`,
`year_month`	Year/Month	Year and month in `YYYY-MM` format e.g., `2019-08`.
`year_week`	Year/Week	Year and week in `YYYY Wk WW` format e.g., `2019 Wk 21`.
`location_name`	Location	A more specific location than country. Can be DMA, city, etc.
`gender_name`	Gender	Gender.
`age`	Age	The specified age group target.
`day_of_week_name`	Day	Day of week.
`campaign_type_name`	Campaign Type	Relevant if set in Tags.
`currency_id`	Currency ID	The id of the currency of `publisher_spend_local` GBP: `1` ,USD: `2`,EUR: `3`.
`creative_copy_direction`	Creative Copy Direction	Only relevant when using creatives thumbnails in Tags.
`creative_copy_line_one`	Creative Copy Line One	Only relevant when using creatives thumbnails in Tags.
`creative_copy_line_two`	Creative Copy Line Two	Only relevant when using creatives thumbnails in Tags.
`creative_copy_title`	Creative Copy Title	Only relevant when using creatives thumbnails in Tags.
`creative_format`	Creative Format	Only relevant when using creatives thumbnails in Tags.
`creative_id`	Creative ID	Only relevant when using creatives thumbnails in Tags.
`creative_image_direction`	Creative Image Direction	Only relevant when using creatives thumbnails in Tags.
`creative_language`	Creative Language	Only relevant when using creatives thumbnails in Tags.
`creative_name`	Creative Name	Only relevant when using creatives thumbnails in Tags.
`creative_primary_colour`	Creative Primary Colour	Only relevant when using creatives thumbnails in Tags.
`creative_theme_name`	Creative Theme	Only relevant when using creatives thumbnails in Tags.
`creative_thumbnail`	Creative Thumbnail	Only relevant when using creatives thumbnails in Tags.
`targeting_name`	Targeting	Additional targeting, e.g., lookalike or custom audience.

","event":[{"listen":"prerequest","script":{"id":"3e488ff3-98cd-42e0-9f91-1fd076e1b24d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5477d22e-076d-4f85-9012-a8c76211fcdb","type":"text/javascript","exec":[""]}}],"_postman_id":"1f7e21b6-c265-45ff-8473-1cb31337b54f"}],"event":[{"listen":"prerequest","script":{"id":"7a6e4ceb-0747-4faf-8fab-5d75c5b3e9d2","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"172d5aff-23be-4ca2-8bb0-f8b8fa712cfa","type":"text/javascript","exec":[""]}}]}

Requirements

Version

Limits

Rate

Parameters

Metrics and dimensions

Date ranges

Response codes

Base path

Pages

AND

OR

Combined

Possible values

Read more

Activity data for performance metrics

Activity data for conversion metrics

Cohort data for conversion metrics

Primary dimensions

Secondary dimensions