This guide is for Singular analytics partners who want to integrate with Singular by providing access to their reporting API. Learn more in the Integrating with Singular Analytics FAQ.

If you are a Singular customer, see Guide to the Singular Reporting API and the Reporting API Reference instead.

Minimum Requirements

To integrate with Singular, your API must provide the following:

Method: GET or POST
API response format: JSON or CSV
Data:
- App Store ID/package name (to identify individual apps) OR App / Brand Name + OS / Platform
- Campaign Name
- Cost
- The data must be broken down by day (date)
Query parameters: Singular should be able to request data by Start Date and End Date
Filtering: Singular should be capable of filtering data for individual clients.

Notes on Filtering: Kindly note that if your API requires unique credentials for each client, there is no necessity to implement additional filtering mechanisms.

Additional Data (Recommended)

To provide our shared clients with the highest reporting granularity, we encourage you to provide as many additional dimensions and metrics as possible from the list below:

Dimensions (Breakdowns)

Dimension	Description
app	The name of the app or brand
site_public_id	iOS apps: The app's store ID in the Apple App Store (e.g., 144175066) Android apps: The package name in Google Play (e.g., com.example.myapp)
campaign_name	The campaign name
campaign_id	The internal ID for campaign within the network's system
campaign_url	The campaign URL, a.k.a tracking URL/store URL
sub_campaign_name	The name of the ad group/ad set, if applicable
sub_campaign_id	The ID of the ad group/ad set, if applicable
country	Country code (2-letter) the ad was served in (e.g., UK)
os	The operating system of the marketed product. For an app, this indicates which app store the app is sold in, e.g., "iOS" or "Android". For non-mobile products, this is "web".
platform	The platform of the marketed product, e.g., "iPhone" or "iPad".
creative_name	The name of the creative or ad
creative_id	The ID of the creative or ad
creative_url	The URL to the creative assets (Image/Video)
creative_text	The text portion of the creative, if any
creative_width	Creative width in pixels
creative_height	Creative height in pixels
publisher_site_name	The name of the publisher (app) in which the ad has been displayed
publisher_site_id	The public ID of the publisher (app) in which the ad has been displayed
publisher_id	The hashed ID of the publisher (app) in which the ad has been displayed
currency	ISO 4217 3-Letter Currency Code (e.g., USD)
adnetwork_name	The name of the ad network (if you are an agency and you are providing campaign data from multiple ad networks)

Metrics

Metric	Description
impressions	Ad views
clicks	Ad clicks
installs	App installs or conversions

Implementation Examples

Here are examples of API requests and responses that Singular can work with.

Request (GET):

https:///api.examplepartner.com/api/v2.0/reporting/4ru34ur3u4u5i3pteqrt?start_date=2022-01-01&end_date=2022-04-01

The response in CSV:

Date,campaign_name,site_public_id,os,creative_name,creative_id,creative_url,Impressions,Clicks,Installs,Cost
2022-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,interstitial,3,http://examplepartner.com/interstitials4.jpg,292088,11244,238,166.6 
2022-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,2,http://examplepartner.com/banner2.jpg,16444743,86716,4366,3056.2 2022-01-01,Fresh Air iOS Campaign 
(US),1195648107,iOS,banner,1,http://examplepartner.com/banner1.jpg, 802797,40263,1800,3960.0 
2022-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,video,3,http://examplepartner.com/video3.jpg,398590,17107,763,2479.75 
2022-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,4,http://examplepartner.com/banner4.jpg,423573,15429,454,317.8 
2022-01-02,Fresh Air iOS Campaign (US),1195648107,iOS,interstitial,2,http://examplepartner.com/interstitials2.jpg,1425602,69436,2771,6096.2

Request (GET):

https:///api.examplepartner.com/api/v2.0/reporting/4ru34ur3u4u5i3pteqrt?start_date=2022-01-01&end_date=2022-04-01&format=JSON

The response in JSON:

[ { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "interstitial ",
"creative_id": 3,
"creative_url": http://examplepartner.com/interstitials4.jpg
"impressions": 292088,
"clicks": 11244,
"installs": 238,
"cost": "166.6" 
}, { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 2,
"creative_url": http://examplepartner.com/banner2.jpg
"impressions": 16444743,
"clicks": 86716,
"installs": 4366,
"cost": "3056.2" 
}, { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 1,
"creative_url": http://examplepartner.com/banner1.jpg
"impressions": 802797,
"clicks": 40263,
"installs": 1800,
"cost": "3960.0" 
}, { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "banner ",
"creative_id": 4,
"creative_url": http://examplepartner.com/banner4.jpg
"impressions": 398590,
"clicks": 17107,
"installs": 763,
"cost": "2479.75" 
}, { 
"date": "2022-01-01",
"campaign_name": "Fresh Air iOS Campaign (US)",
"site_public_id": 1195648107,
"os": iOS,
"creative_name": "interstitial ",
"creative_id": 2,
"creative_url": http://examplepartner.com/interstitials2.jpg
"impressions": 423573,
"clicks": 15429,
"installs": 454,
"cost": "317.8" 
}]

Integrating with Singular Analytics via API (Partners)

Minimum Requirements

Additional Data (Recommended)

Dimensions (Breakdowns)

Metrics

Implementation Examples