Learn how to use the Singular API to pull your SKAN (SKAdNetwork) data.

For SKAdNetwork Reporting in the Singular web app, see the SKAdNetwork Reporting FAQ.
For Singular's other reporting API endpoints (not SKAdNetwork-related), see the Reporting API Reference.
If you are a Singular partner, you may be looking for the Get SKAN Conversion Info API Reference (SKadNetwork API for Singular Partners).

Note: All Singular API requests require an API key. To retrieve the key, log into your account and go to Settings > API. You can insert the key in the api_key parameter in your request, or provide the token under an Authorization HTTP header.

Create Async SKAdNetwork Report Endpoint

POST

https://api.singular.net/api/v2.0/create_async_skadnetwork_raw_report

Usage

This endpoint generates an asynchronous report query for Singular SKAdNetwork data and returns a Report ID. The next step is to query the Get Report Status endpoint to see when the report is done and to get a download URL.

Sample Query (Python)

import requests

url = "https://api.singular.net/api/v2.0/create_async_skadnetwork_raw_report"
params = {"api_key": API_KEY}
data = {
   "skadnetwork_date_type": "skan_postback_date",
   "start_date": "2021-01-01",
   "end_date": "2021-01-01",
   "dimensions": "app,source,skan_network_id,skan_campaign_id,skan_app_id,skan_publisher_id,skan_conversion_value,skan_redownloads,skan_validated,country_field",
   "metrics": "skan_installs",
   "filters": '[{"dimension": "skan_validated", "operator": "in", "values": ["false"]},{"dimension": "skan_redownloads", "operator": "in", "values": ["true"]}]',
   "time_breakdown": "all",
}

response = requests.post(url=url, params=params, data=data)

Query Parameters

Parameter	Format	Description	Example
Basic Parameters
api_key	String	API key provided in the Singular console
start_date	Date		'2020-12-01'
end_date	Date		'2020-01-10'
time_breakdown	String	How to break down the results: - "day" - "week" - "month" - "all" (display aggregated data over the entire date range)	'all'
skadnetwork_date_type	String	Choose which type of date you want the report to be based on: - "skan_postback_date" (default) - the date the SKAN postback was sent by the device. - "estimated_install_date" - the install date as calculated by Singular (see How does Singular calculate the install date?).	'estimated_install_date'
Field Selection Parameters
dimensions	String	A comma-separated list of dimensions. See the table below for the dimensions available for SKAdNetwork reports are.
metrics	String	A comma-separated list of metrics. The only metric available for SKAdNetwork reports at this point is skan_installs.	'skan_installs'
Filtering Parameters
app	String	A comma-separated list of app names to filter the query results by. To retrieve a list of app names, use the Filters endpoint.	'my_app1, my app2'
source	String	A comma-separated list of ad networks (and other sources) to filter by. To retrieve a list of ad network names, use the Filters endpoint.	'facebook,adwords'
filters		An array of JSON objects where each object contains a dimension, an operator, and a value to filter by. Use this parameter to apply more advanced filtering. Note that if you specify more than one filter they will be applied with an AND relation. Available filters for SKAdNetwork reports (see details in the Available Dimensions table below) "country_field" "skan_redownloads" "skan_validated"	'[{"dimension": "skan_validated", "operator": "in", "values": ["false"]}, {"dimension": "skan_redownloads", "operator": "in", "values": ["true"]}]'
Formatting Parameters
format	String	The format in which the query results will be delivered. Options: "json" (default) or "csv".	'csv'
country_code_format	String	Either "iso3" (default) or "iso"	'iso'

Available Dimensions

Dimension	Description
skan_app_id	The value of the 'app-id' parameter in Apple's SKAdNetwork postback.
skan_network_id	The value of the 'ad-network-id' parameter in Apple's SKAdNetwork postback.
skan_campaign_id	The value of the 'campaign-id' parameter in Apple's SKAdNetwork postback.
skan_publisher_id	The value of the 'source-app-id' parameter in Apple's SKAdNetwork postback.
app	The app name in Singular (derived from skan_app_id).
source	The ad network name as it is listed in Singular (derived from skan_network_id).
country_field	Derived from the IP that's included in the SKAdNetwork postback.
skan_conversion_value
skan_redownloads	Apple's SKAdNetwork postbacks include a "redownload" field. According to Apple, this is set to true if the app has already been downloaded and installed by the same user (same Apple ID). Singular marks every SKAdNetwork install accordingly as either a "download" or a "redownload".
skan_validated	As a part of Singular's SKAdNetwork solution, Singular not only receives and parses SKAdNetwork postbacks from ad networks, but also checks with Apple to confirm that each postback represents an actual install. Validation ensures that installs are not fraudulent.

SKAN-Specific Error Codes

Singular uses standard HTTP response codes to indicate the success or failure of an API request. In general, 200 codes correspond to success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and 5xx codes are for other issues.

Error message	Solution
There is no SKAdNetwork data configured.
'is_skadnetwork_report' param expected to receive value 'true', got 'xxx' instead	Make sure your parameter values match the permitted values listed in the table above.
'skadnetwork_date_type" param expected to receive one of the following values (...), got '...' instead.
The dimensions ['...'] can not be requested in an SKAdNetwork report.
The metrics ['...'] can not be requested in an SKAdNetwork report.
The '...' filter expected to receive one of the following values ['false','true', got '...' instead.