Server-to-Server (S2S) API Endpoint Reference

This reference article lists the API endpoints offered by Singular for S2S integrations.

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

Update [November 2021]: You should now report the Android Install Referrer through the Session Notification Endpoint (not Event Notification). This makes the install referrer available to Singular immediately when the user opens the app, and follows Google's best practices. For more information, see Sending the Google Play Install Referrer (Android).

 

Authentication and Status Codes

Any call to the S2S API has to include your SDK Key. To retrieve it, log into Singular and go to "Developer Tools > SDK Integration > SDK Keys".

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 Session Parameters

Parameter Description Supported Platforms Example
a Singular SDK Key. iOS, Android,
PC, Console
your_org_name_sh868sdjv
p One of the following Platforms:
Android, iOS, PC, Xbox, Playstation, Nintendo, MetaQuest or CTV
iOS, Android,
PC, Console
Android
i Package Name (Android) or Bundle ID (iOS) of your application. iOS, Android,
PC, Console
com.singular.app
ip The IP of the device. IPV4 only; IPV6 not supported. iOS, Android,
PC, Console
172.58.29.235
ve OS Version of the device at session time. iOS, Android,
PC, Console
9.2
install_ref Google Install Referrer Information Android (Google Play) Learn more
meta_ref Meta Install Referrer Information Android Learn more
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 the app opened via any 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 Lower-case raw Google advertising ID with dashes. Android (Google Play) 8ecd7512-2864-440c-93f3-a3cabe62525b
asid The App Set ID (for Android 12+ devices). This should be send if the Google advertising ID (aifa) is not available. Learn more Android (Google Play) edee92a2-7b2f-45f4-a509-840f170fc6d9
amid The Amazon Advertising ID with dashes. Available with Amazon devices. Android (Amazon) df07c7dc-cea7-4a89-b328-810ff5acb15d
oaid The Open Advertising ID with dashes, generally used in China domestic devices. Available either with integrated MSA SDK or Huawei OAID SDK Android 01234567-89abc-defe-dcba-987654321012
andi For non-Google Play Android apps only. Lower-case raw android ID.

Only send this if no other device identifiers are available.
Android fc8d449516de0dfb
sdid

PC/Console: A client-side generated UUIDv4 representing a unique app install.

PC, Console 40009df0-d618-4d81-9da1-cbb3337b8dec
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 InstallSourceInfo.getInitiatingPackageName()

 

The installing store on PC, supported/recommended values are: steam, epic, microsoftstore, humblestore, gog, selfdistributed

Android, PC

Android:

com.vending.android (Android)

steam (PC)


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,
PC, Console
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
singular_link_resolve_required Used to resolve a Singular short link. Must be sent with value in the "openuri" that is a Singular short link. See Short Link handling.

iOS,
Android

true
att_authorization_status *

Available iOS 14 and above.  The App Tracking Transparency authorization status.

Supported values are:

  • 0 - Undetermined, the ATT prompt was not shown yet.  IDFA unavailable on iOS 14.5+
  • 1 - Restricted, the user has disabled the option to show the  ATT prompt.  IDFA unavailable.
  • 2 - Denied, the user has seen the ATT prompt and denied authorization.  IDFA unavailable
  • 3 - Authorized, the user has seen the ATT prompt and graned authorization.  IDFA is available
iOS 3

* Note: Starting with iOS 14.5, the App Tracking Transparency (ATT) prompt is required to access the IDFA. Even if you don't implement the ATT prompt, we require that you pass the ATT authorization status to Singular (with the value "0", indicating "undetermined").

Optional Session Parameters

Parameter Description Supported Platforms Example
custom_user_id User ID iOS, Android,
PC, Console
 123456789abcd
n Human-readable name of the application as displayed in the UI. iOS, Android,
PC, Console
MyCoolApp
utime Time of the session in 10 digit UNIX time. iOS, Android,
PC, Console
1483228800
umilisec Time of the session in milliseconds 13 digit UNIX time. iOS, Android,
PC, Console
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,
PC, Console
true
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 b0adf7c9730763f88e1a048e28c68a9f806ed032fb522deb...ff5bfba010a9b052
ua User Agent of the device iOS, Android,
PC, Console
Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148
attribution_token Used to attribute Apple Search Ads for iOS 14.3 and above.  This value is available via the AdServices framework.  Learn how to retrieve it in Implementing Apple Search Ads via AdServices iOS G9i5hC8lQJeGOfmS+MFycll/02...AAABBEQQBQA=
skan_conversion_value The latest SKAdNetwork conversion value at the time of this session notification (learn more about SKAdNetwork implementation). 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
global_properties You can define up to 5 global properties. Each property key and value can be up to 200 characters long. If you pass a longer property name or value, it will be truncated to 200 characters. The value must be a URLEncoded JSON Object. iOS, Android,
PC, Console
%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D
data_sharing_options

Pass this optional value to indicate the end-user's consent to share information. If set, this value must be persisted and passed on every subsequent /launch and /evt request for the user. 

Pass "limit_data_sharing":false to indicate that the user consented (opted in) to share their information.

Pass "limit_data_sharing":true if the user refused.

Optional

%7B%22limit_data_sharing%22%3Atrue%7D

Sample API Call

Python HTTP cURL Java
import requests
  import json
  
   SDK_KEY = '[sdk_key from Developer tools > SDK Integration > SDK keys]'
   LAUNCH_URL = 'https://s2s.singular.net/api/v1/launch'
  
   params = {
       'a': SDK_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',
'global_properties': json.dumps({"key1":"value1","key2":"value2"}) } 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 Event Parameters

Parameter Description Supported Platforms Example
n

Name of the event.

Limitation: max 32 ASCII characters 

It is recommended to use Singular's standard event naming convention.

iOS, Android, Web,
PC, Console
sng_add_to_cart
a Singular SDK Key. iOS, Android, Web,
PC, Console
a42be1d8119389dd36c7_acbeaf6abcd8
p One of the following Platforms:
Android, iOS, Web, PC, Xbox, Playstation, Nintendo, MetaQuest or CTV
iOS, Android, Web,
PC, Console
Android
i Package Name (Android) or Bundle ID (iOS) of your mobile application or ProductID from WebSDK. iOS, Android, Web,
PC, Console
com.yourcompany.app
ip The IP of the event. IPV4 only; IPV6 not supported. iOS, Android, Web,
PC, Console
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 Lower-case raw Google advertising ID with dashes. Android (Google Play) 8ecd7512-2864-440c-93f3-a3cabe62525b
asid The App Set ID (for Android 12+ devices). This identifier should be sent if the Google advertising ID (aifa) is not available. Learn more Android (Google Play) edee92a2-7b2f-45f4-a509-840f170fc6d9
amid The Amazon Advertising ID with dashes. Available with Amazon devices. Android (Amazon) df07c7dc-cea7-4a89-b328-810ff5acb15d
oaid The Open Advertising ID with dashes is generally used in China domestic devices. Available either with integrated MSA SDK or Huawei OAID SDK Android 01234567-89abc-defe-dcba-987654321012
andi For non-Google Play Android apps only. Lower-case raw android ID.

This identifier should only be sent if no other device identifiers are available.
Android fc8d449516de0dfb
sdid

Web: The UUIDv4 device ID provided by Singular's WebSDK Learn more

PC/Console: A client-side generated UUIDv4 representing a unique app install.

Web, PC, Console 40009df0-d618-4d81-9da1-cbb3337b8dec
ve OS Version of the device at event time. iOS, Android, Web,
PC, Console
9.2
att_authorization_status * The App Tracking Transparency authorization status. Available iOS 14+.

Supported values:

  • 0 - Undetermined, the ATT prompt was not shown yet.  IDFA unavailable on iOS 14.5+
  • 1 - Restricted, the user has disabled the option to show the  ATT prompt.  IDFA unavailable.
  • 2 - Denied, the user has seen the ATT prompt and denied authorization. IDFA unavailable
  • 3 - Authorized, the user has seen the ATT prompt and graned authorization. IDFA is available
iOS 3

* Note: Starting with iOS 14.5, the App Tracking Transparency (ATT) prompt is required in order to access the device's IDFA. Even if you don't implement the ATT prompt, we require that you pass the ATT authorization status to Singular (with the value "0", indicating "undetermined").

Optional Event Parameters

Parameter Description Supported Platforms Example
custom_user_id User ID  iOS, Android, Web,
PC, Console
123456789abcd
utime Time of the event in 10 digit UNIX time. Note: The time MUST NOT be less than the Install Time. iOS, Android, Web,
PC, Console
1483228800
umilisec Time of the event in milliseconds 13 digit UNIX time. Note: The time MUST NOT be less than the Install Time. iOS, Android, Web,
PC, Console
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, Web,
PC, Console
true
e

Custom event attributes in JSON format.

It is highly recommended to use Singular's standard event attribute naming convention.

iOS, Android, Web,
PC, Console
%7B%22sng_attr_content_id%22%3A5581%2C
sng_attr_content%22%3A%22XBox%22%2C%22
sng_attr_content_type%22%3A%22electronics%22%7D
global_properties You can define up to 5 global properties. Each property key and value can be up to 200 characters long. If you pass a longer property name or value, it will be truncated to 200 characters. The value must be a URLEncoded JSON Object. iOS, Android, Web,
PC, Console
%7B%22key1%22%3A%22value1%22
%2C%22key2%22%3A%22value2%22%7D
data_sharing_options

Pass this optional value to indicate the end-user's consent to share information. If set, this value must be persisted and passed on every subsequent /launch and /evt request for the user. 

Pass "limit_data_sharing":false to indicate that the user consented (opted in) to share their information.

Pass "limit_data_sharing":true if the user refused.

Optional

%7B%22limit_data_sharing%22%3Atrue%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, Web, PC, Console True
amt The currency amount. This should be used in conjunction with the cur parameter. iOS, Android, Web, PC, Console 2.51
cur The ISO 4217 three-letter currency code. This should be used in conjunction with the amt parameter. iOS, Android, Web, PC, Console 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, Web, PC, Console

com.example.product

purchase_transaction_id The transaction identifier iOS, Android, Web, PC, Console

iOS: 380000123004321

Android: GPA.1234-1234- 1234-12345 

Sample API Call

Python HTTP cURL Java
import requests
  import json
  
  SDK_KEY = '[sdk_key from Developer tools > SDK Integration > SDK keys]'
  EVENT_URL = 'https://s2s.singular.net/api/v1/evt'
  
  params = {
   'n': 'levelup',
   'e': json.dumps({"level": "10"}),
   'a': SDK_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',
'global_properties': json.dumps({"key1":"value1","key2":"value2"}) } result = requests.get(EVENT_URL, params=params) print result.json()