Server-to-Server (S2S) API Endpoint Reference

This reference article lists the API endpoints offered by Singular for S2S integrations. For a step-by-step guide to creating an S2S integration, see Singular Server-to-Server (S2S) Integration Guide.

If you are looking for information about pulling reports from Singular via API, see the Reporting API Reference.

Note: Server-to-server integrations are only available to Enterprise customers.

 

Authentication and Status Codes

Any call to the S2S API has to include your SDK API key. To retrieve it, log into Singular, go to Settings > SDK Keys, and copy the API Key.

The returned HTTP status code in any call to the S2S API is 200 if the call is successful. Any other code means you should retry the call.

List of Singular S2S API Endpoints

The following API endpoints are available:

Session Notification GET https://s2s.singular.net/api/v1/launch Report a new session to Singular.
Event Notification GET https://s2s.singular.net/api/v1/evt Report an in-app event to Singular.

Session Notification Endpoint

GET https://s2s.singular.net/api/v1/launch

 Use the session notification endpoint to report a session to Singular.

Required Parameters

Parameter Description Supported Platforms Example
a Singular SDK Key. iOS, Android your_org_name_sh868sdjv
p Platform Android or iOS. iOS, Android Android
i Package Name (Android) or Bundle ID (iOS) of your application. iOS, Android com.singular.app
ip The IP of the device. iOS, Android 172.58.29.235
ve OS Version of the device at session time. iOS, Android 9.2
ma Make of the device hardware, typically the consumer-facing name (e.g., Samsung, LG, Apple). This parameter must be used with the model parameter. iOS, Android samsung
mo Model of the device hardware (e.g., iPhone 4S, Galaxy SIII). This parameter must be used with the make parameter. iOS, Android SM-G935F
lc The IETF local tag for the device, using two-letter language and country code separated by an underscore. iOS, Android en_US
bd Build of the device, URL encoded iOS, Android Build%2F13D15
openuri If app opened via deep link/Universal Link/app link, the encoded deep link URL value iOS, Android myapp%3A%2F%2Fhome%2Fpage%3 Fqueryparam1%3D value1%26queryparam2%3 Dvalue2
idfa For iOS apps only. Upper-case raw advertising ID with dashes. iOS DFC5A647-9043-4699-B2A5-76F03A97064B
idfv For iOS apps only. Upper-case raw IdentifierForVendor with dashes. iOS 21DB6612-09B3-4ECC-84AC-B353B0AF1334
aifa For Android apps only. Lower-case raw advertising ID with dashes. Android 8ecd7512-2864-440c-93f3-a3cabe62525b
andi For Android apps only. Lower-case raw android ID. Required only when Android Advertising ID is not available on the device. Android fc8d449516de0dfb
dnt Pass 1 if do not track is enabled, 0 if do not track is disabled. iOS, Android 1
app_v App version iOS, Android 1.2.3
install_source Install source package name on Android e.g: 'com.android.vending'. To retrieve this value use PackageManager.getInstallerPackageName Android com.vending.android
install_receipt The receipt received from the install. Learn how to retrieve it at iOS Install Receipt iOS MIISqwYJKoZI...cNqts0jvcNvPcK7 yuj0KhJ9nTTQ54kDKfReihzc6aw==
install Install flag. 'true' if the session was the first after installing the app. 'false' otherwise. Required for Reinstall tracking capabilities. iOS, Android false
install_time The time of the first app install as UNIX time. To retrieve this value use the link on the platform. iOS, Android 1510040127
update_time The time of the last app update as UNIX time.To retrieve this value use the link on the platform. iOS, Android 1510040127
ddl_enabled Deferred deep link flag. 'true' if the server expects a deferred deep link URL to be returned. 'false' otherwise. See our section on deferred deep linking for more details iOS, Android true
att_authorization_ status * Available iOS 14 and above.  The App Tracking Transparency authorization status. iOS 3

* On September 3rd, Apple announced an update delaying certain privacy features on iOS 14, specifically removing the requirements to use AppTrackingTransparency to access the IDFA until "early next year".  With this change, we recommend NOT implementing the AppTrackingTransprency pop-up with the iOS 14 launch, as IDFA is still accessible as of iOS 14 beta 7.  Read more about iOS 14 beta 7 and the IDFA here

Att_authorization_status remains documented above, for the future unannounced version of iOS 14 where AppTrackingTransparency will be required before the IDFA can be retrieved.

Optional Parameters

Parameter Description Supported Platforms Example
custom_user_id User ID iOS, Android  123456789abcd
n Human-readable name of the application as displayed in the UI. iOS, Android MyCoolApp
utime Time of the session in UNIX time. iOS, Android 1483228800
umilisec Time of the session in milliseconds UNIX time. iOS, Android 1483228800000
dntoff Pass 0 if "do not track" is enabled or 1 if "do not track" is disabled. iOS, Android 0
c Connection type 'wifi' or 'carrier'. iOS, Android wifi
cn Carrier name of the internet provider. iOS, Android Comcast
use_ip Extract the IP field from the HTTP request instead of the 'ip field. Don't use this with the IP parameter iOS, Android false
fcm Firebase Cloud Messaging Device Token. Required for Android Uninstall Tracking Android bk3RNwTe3H0CI2k_ HHwgIpoDKCIZvvD MExUdFQ3P1
gcm Google Cloud Messaging Device Token. Required for Android Uninstall Tracking (legacy) Android bk3RNwTe3H0CI2k_ HHwgIpoDKCIZvvDM ExUdFQ3P1
apns_token Apple Push Notification Service Device Token. Required for iOS Uninstall Tracking iOS b0adf7c9730763f88e1 a048e28c68 a9f806ed032fb522deb ff5bfba010a9b052
ua User Agent of the device iOS Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148
skan_conversion_value The latest SKAdNetwork conversion value, at the time of this session notification (To learn more about SKAdNetwork  implementation, read here) iOS 0 - 63
skan_first_call_timestamp Unix timestamp of the first call to the underlying SkAdNetwork API (To learn more about SKAdNetwork implementation, read here) iOS 1483228800
skan_last_call_timestamp Unix timestamp of the latest call to the underlying SkAdNetwork API, at the time of this session notification (To learn more about SKAdNetwork implementation, read here) iOS 1483228800

Sample API Call

Python HTTP cURL Java
import requests
 import json

 API_KEY = 'api_key_from_sdk_page'
 LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'

 params = {
     'a': API_KEY,
     'p': 'Android',
     'i': 'com.singular.app',
     'ip': '10.1.2.3',
     've': '9.2',
     'ma': 'samsung',
     'mo': 'SM-G935F',
     'lc': 'en_US',
     'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
     'andi': 'fc8d449516de0dfb',
     'utime': 1483228800,
     'dnt': 0,
     'install':'true',
     'n': 'MyCoolApp',
     'c': 'wifi',
     'cn': 'Comcast',
     'bd': 'Build/13D15',
     'fcm':'bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1',
     'app_v':'1.2.3',
     'openuri':'myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1',
     'ddl_enabled':'false',
     'install_source': 'com.android.vending',
     'install_time': 1510040127,
     'update_time': 1510090877,
'custom_user_id': '123456789abcd' } result = requests.get(LAUNCH_URL, params=params) print result.json()

Event Notification Endpoint

GET https://s2s.singular.net/api/v1/evt

Use this endpoint to report any event occurring in your application other than the session.

Required Parameters

Parameter Description Supported Platforms Example
n Name of the event. iOS, Android ViewItem
a Singular SDK Key. iOS, Android a42be1d8119389dd36c7 acbeaf6abcd8
p Platform Android or iOS. iOS, Android Android
i Package Name (Android) or Bundle ID (iOS) of your application. iOS, Android com.yourcompany.app
ip The IP of the event. iOS, Android 172.58.29.235
idfa For iOS apps only. Upper-case raw advertising ID with dashes. iOS DFC5A647-9043-4699-B2A5-76F03A97064B
idfv For iOS apps only. Upper-case raw IdentifierForVendor with dashes. iOS 21DB6612-09B3-4ECC-84AC-B353B0AF1334
aifa For Android apps only. Lower-case raw advertising ID with dashes. Android 8ecd7512-2864-440c-93f3-a3cabe62525b
andi For Android apps only. Lower-case raw android ID. Required only when Android Advertising ID is not available on the device. Android fc8d449516de0dfb
att_authorization_ status * Available iOS 14 and above.  The App Tracking Transparency authorization status. iOS 3

* On September 3rd, Apple announced an update delaying certain privacy features on iOS 14, specifically removing the requirements to use AppTrackingTransparency to access the IDFA until "early next year".  With this change, we recommend NOT implementing the AppTrackingTransprency pop-up with the iOS 14 launch, as IDFA is still accessible as of iOS 14 beta 7.  Read more about iOS 14 beta 7 and the IDFA here

Att_authorization_status remains documented above, for the future unannounced version of iOS 14 where AppTrackingTransparency will be required before the IDFA can be retrieved.

Optional Parameters

Parameter Description Supported Platforms Example
custom_user_id User ID  iOS, Android 123456789abcd
utime Time of the event in UNIX time. Note: The time MUST NOT be less than the Install Time. iOS, Android 1483228800
umilisec Time of the event in milliseconds UNIX time. Note: The time MUST NOT be less than the Install Time. iOS, Android 1483228800000
use_ip Extract the IP field from the HTTP request. If you set this to true, don't provide the ip parameter. iOS, Android false
e Custom event attributes in JSON format. iOS, Android %7B%22item_name%22%3A %20%22XBox%22%2C%0A
%22item_sku%22%3A%2011235813%7D
skan_conversion_value The latest SKAdNetwork conversion value, at the time of this event notification (To learn more about SKAdNetwork  implementation, read here) iOS 0 - 63
skan_first_call_timestamp Unix timestamp of the first call to the underlying SkAdNetwork API (To learn more about SKAdNetwork implementation, read here) iOS 1483228800
skan_last_call_timestamp Unix timestamp of the latest call to the underlying SkAdNetwork API, at the time of this event notification (To learn more about SKAdNetwork implementation, read here) iOS 1483228800

Parameters for Revenue Events

Parameter Description Supported Platforms Example
is_revenue_event Whether it's a revenue event. You can omit this if the event name is __iap__ or a non-zero amt is provided. iOS, Android True
amt The currency amount. This should be used in conjunction with the cur parameter. iOS, Android 2.51
cur The ISO 4217 three-letter currency code. This should be used in conjunction with the amt parameter. iOS, Android EUR
purchase_receipt The receipt received from a purchase. See instructions below on how to retrieve it from Android, iOS iOS, Android

iOS:
MIISqwYJKoZI...cNqts0jvcNvPcK7y
uj0KhJ9nTTQ54kDKfReihzc6aw==

Android:
{"orderId":"GPA.1234",
"packageName":"com.example",
"productId":"com.example.product",
"purchaseTime":1417113074914,
"purchaseState":0,
"purchaseToken":"hakfcimbk... pM"} 

receipt_signature The signature used to sign the purchase receipt Android TyVJfHg8OAoW7W4wuJt... 5agEDMnNXvhfrw==
purchase_product_ id The product SKU identifier iOS, Android

com.example.product

purchase_ transaction_id The transaction identifier iOS, Android

iOS: 380000123004321

Android: GPA.1234-1234- 1234-12345 

Sample API Call

Python HTTP cURL Java
import requests
import json

API_KEY = 'api_key_from_sdk_page'
EVENT_URL = 'https://s2s.singular.net/api/v1/evt'

params = {
 'n': 'levelup',
 'e': json.dumps({"level": "10"}),
 'a': API_KEY,
 'p': 'Android',
 'i': 'com.yourcompany.app',
 'ip': '10.1.2.3',
 'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
 'andi': 'fc8d449516de0dfb',
 'utime': 1483228800,
 'custom_user_id': '123456789abcd'
}

result = requests.get(EVENT_URL, params=params)
print result.json()

Was this article helpful?