EVENT Endpoint API Reference

Server-to-Server Use Case

The EVENT API enables event tracking in your applications. When your app forwards device-specific data to your server, which then transmits it to Singular's servers, the platform processes this information for: Event Attribution, and App Revenue Metrics. This processed data automatically populates your reports, export logs, and configured postbacks, providing comprehensive analytics for your marketing campaigns.

The Singular REST API enables direct server-to-server integration as an alternative to the SDK. While the SDK automatically collects device and app data, the S2S approach requires you to:

Collect required data points from your app
Forward this data to your server
Update/Get device details from device graph
Forward Event to Singular via REST API

Key Points

Flexibility: Full control over data collection and transmission
Feature Parity: Supports all SDK functionality when proper data is provided
Integration Path: Client → Your Server → Singular API
Real-time processing: One request at a time, no batch processing
Sequential data flow: Events must be processed in chronological order
Data Deduplication: Singular does not deduplicate received data. It is recommended to send one(1) successful Request and save logs in the event a Request should be replayed.
Data Validation: Device-level data is permanent and cannot be deleted once ingested. Implement thorough data validation before sending data to Singular to ensure accuracy.

Prerequisites

A Session must be established before any event tracking is received
Invalid session order will result in data inconsistencies

Getting Started

The EVENT endpoint documentation provides:

Required parameters
Optional parameters
Request Examples
Response Codes & Errors
Event Testing

This server-side approach gives you more control over your integration while maintaining all SDK capabilities.

Reporting Events

Singular can collect data about in-app events to help analyze the performance of your marketing campaigns. Events can include any user interaction from logins and registrations to leveling up in a gaming app.

Before you implement an SDK/S2S integration with Singular, you should have a list of the events your organization wants to track (see Defining In-App Events).

The event name you include in the call is how the event will be identified in Singular reports, exports, and postbacks.

Notes:

Singular recommends passing events using Singular's standard event and attribute naming convention. Using standard events streamlines mapping and compatibility with your partners standard events in integrations.
We highly recommend passing event names and other attributes in English for compatibility with any third-party partners and analytics solutions you may want to use.

Important:

Event names are limited to 32 ASCII characters. For non-ASCII characters, the limit is 32 bytes once converted to UTF-8.
Event attributes and values are limited to 500 ASCII characters.

Event API Endpoint

HTTP Method and Event Endpoint

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

Required Parameters

The following table lists the required parameters that this endpoint supports. All of the parameters listed are query parameters.

GET /api/v1/evt?param1=value1&param2=value2

All required parameters must be included in EVENT API requests
Parameters should follow specified format and data types

Required Parameters
API Key
Parameter	Description
`a`	`string` The a parameter specifies the Singular SDK Key. Retrieve the SDK Key from the Singular UI, under Developer Tools in the Main Menu. Note: Do not use the reporting API Key as this will result in rejected data. Example Value: `sdkKey_afdadsf7asf56`
Device Identifier Parameters
Parameter	Description
`idfa` Supported Platforms: iOS	`string` The idfa parameter specifies the Identifier for Advertisers (IDFA) which helps advertisers track and attribute user actions (e.g., ad clicks, app installs) to specific campaigns, enabling precise ad targeting and campaign optimization. Starting with iOS 14.5, users must opt-in via the App Tracking Transparency (ATT) framework before apps can access the IDFA. If users do not opt-in to IDFA then the IDFA will be unavailable resulting in limiting tracking capabilities. If the IDFA is unavailable then omit the parameter from the request. Do not pass NULL or empty string in the request. How to retrieve the IDFA Identifier Example Value: `DFC5A647-9043-4699-B2A5-76F03A97064B`
Parameter	Description
`idfv` Supported Platforms: iOS	`string` The idfv parameter specifies the Identifier for Vendors (IDFV), a unique identifier assigned by Apple to a device, which is specific to a particular vendor or developer. It remains consistent across all apps from the same vendor on a given device, allowing the vendor to track user behavior and interactions across their app ecosystem without identifying the user personally. The IDFV is required on all request regardless of ATT status or the presence of the IDFA. How to retrieve the IDFV Identifier Example Value: `21DB6612-09B3-4ECC-84AC-B353B0AF1334`
Parameter	Description
`aifa` Supported Platforms: Android (Google Play Devices)	`string` The aifa parameter specifies the Google Advertising Identifier (GAID), also known as AIFA in Singular or Android Advertising ID (AAID). This identifier is a unique, user-resettable identifier assigned to Android devices. It helps advertisers and app developers track and attribute user actions (e.g., ad clicks, app installs) across apps to specific campaigns, enabling precise ad targeting and campaign optimization, while maintaining user privacy. If the AIFA is unavailable then omit the parameter from the request. Only required on Google Play Devices. Omit the parameter on Non-Google Play devices. Do not pass NULL or empty string in the request. How to retrieve the AIFA Identifier Example Value: `8ecd7512-2864-440c-93f3-a3cabe62525b`
Parameter	Description
`asid` Supported Platforms: Android (Google Play Devices)	`string` The asid parameter specifies the Android App Set ID. The ASID provides a way for developers to track users across their own apps in a privacy-conscious manner. It is particularly useful for analytics and fraud prevention but cannot be used for advertising purposes such as personalized ads or measurement. The ASID is required on all request for Google Play Devices, regardless of GAID/AIFA presence. Omit the parameter on Non-Google Play devices. Do not pass NULL or empty string in the request. How to retrieve the ASID Identifier Example Value: `edee92a2-7b2f-45f4-a509-840f170fc6d9`
Parameter	Description
`amid` Supported Platforms: Android (Amazon Devices without Google Play Services)	`string` The amid parameter specifies the Advertising ID is a user-resettable, unique identifier that helps protect the privacy of the user. If you collect information about a user’s behavior to display interest-based ads, or to generate analytics, you must use the Advertising ID; no other identifier or tracking method may be used. Users can reset the Advertising ID or opt out of interest-based ads altogether. The AMID is required on all request for Amazon Devices without Google Play Services. Omit the parameter if AMID is unavailable. Do not pass NULL or empty string in the request. How to retrieve the AMID Identifier Example Value: `df07c7dc-cea7-4a89-b328-810ff5acb15d`
Parameter	Description
`oaid` Supported Platforms: Android (Chinese-manufactured Devices without Google Play Services)	`string` The oaid parameter specifies Open Advertising Identifier (OAID). The OAID is a unique, anonymous identifier used for advertising purposes on Android devices, particularly those manufactured in China. It was introduced by the Mobile Security Alliance (MSA) as an alternative to Google's Advertising ID (GAID) for devices where Google Play Services are unavailable or not supported, such as in the Chinese market. The OAID is primarily used for advertising attribution and user tracking in environments where Google Play Services are restricted, allowing advertisers and developers to track user behavior while maintaining anonymity. OAID is available on most Chinese-manufactured Android devices, including those from brands like Huawei, Xiaomi, and others. It can be accessed using the MSA SDK or Huawei Mobile Services (HMS). The OAID is required on Chinese-manufactured Android devices without Google Play Services. Omit the parameter if OAID is unavailable. Do not pass NULL or empty string in the request. How to retrieve the OAID Identifier Example Value: `01234567-89abc-defe-dcba-987654321012`
Parameter	Description
`andi` Supported Platforms: Android (Non Google Play devices)	`string` The andi parameter specifies the Android ID which is a unique 64-bit identifier generated by the Android operating system when a device is first set up. It is designed to be persistent across the lifetime of the device, but it can be reset under certain conditions such as a factory reset. The Android ID is unique to each device and, starting from Android 8.0 (Oreo), it is scoped per app and per user. This means that different apps on the same device will receive different Android IDs unless they share the same signing key. The Android ID remains constant unless the device undergoes a factory reset or if an app is uninstalled and reinstalled after an OTA (over-the-air) update. The ANDI is prohibited for use on Google Play Devices. Use the AIFA and ASID identifiers mentioned above. The ANDI may be sent to Singular only if no other identifiers are available, and the App is not hosted on Google Play Store. Omit the parameter if other identifiers are available. Do not pass NULL or empty string in the request. How to retrieve the ANDI Identifier Example Value: `fc8d449516de0dfb`
Parameter	Description
`sdid` Supported Platforms: Web PC Xbox Playstation Nintendo MetaQuest CTV	`string` The sdid parameter specifies the Singular Device ID. For Web events, this value is obtained from the Singular Web SDK How to retrieve the Web SDID Identifier For PC and Console Applications, this value is a client-side generated UUIDv4 representing a unique app install. Example Value: `40009df0-d618-4d81-9da1-cbb3337b8dec`
Parameter	Description
`sing` Supported Platforms: Restricted for special use-cases Contact your Solution Engineer or CSM for more information	`string` The sing parameter is restricted to Enterprise customers and specifies a Client defined identifier. Only used in special uses where all other identifiers are not available. This identifier must be enabled by Singular Solution Engineer on an App-by-App bases. Example Value: `da534a95-1b1b-47d4-94b6-07955ec85177`
Device Parameters
Parameter	Description
`p`	`string` The p parameter specifies the platform of the App. The following list contains the allowed case-sensitive parameter values: Android iOS Web PC Xbox Playstation Nintendo MetaQuest CTV Example Value: `Android`
Parameter	Description
`ip`	`string` The ip parameter specifies the public (IPV4) IP Address of the device. IPV6 is not supported. Example Value: `172.58.29.235`
Parameter	Description
`ve`	`string` The ve parameter specifies the OS Version of the device at event time. Example Value: `9.2`
Parameter	Description
`ma` Supported Platforms: Android iOS	`string` The ma parameter specifies the Make of the device hardware, typically the consumer-facing name. This parameter must be used with the model parameter. How to retrieve the Device Make Examples: `Samsung, LG, Apple`
Parameter	Description
`mo` Supported Platforms: Android iOS	`string` The mo parameter specifies the Model of the device hardware. This parameter must be used with the make parameter. How to retrieve the Device Model Examples: `iPhone 4S, Galaxy SIII`
Parameter	Description
`lc` Supported Platforms: Android iOS	`string` The lc parameter specifies the IETF locale tag for the device, using two-letter language and country code separated by an underscore. How to retrieve the Device Locale Example Value: `en_US`
Parameter	Description
`bd` Supported Platforms: Android iOS	`string` The bd parameter specifies the Build of the device, URL-encoded. How to retrieve the Device Build Example Value: `Build%2F13D15`
Application Parameters
Parameter	Description
`i`	`string` The i parameter specifies the App Identifier. This is the Package Name for Android or the Bundle ID for iOS or of your application. case-sensitive parameter values: Package Name for Android Bundle ID for iOS Product ID for Web Your designated identifier for PC, Xbox, Playstation, Nintendo, MetaQuest, or CTV Example Value: `com.singular.app`
Parameter	Description
`att_authorization_status` Supported Platforms: iOS	`int` The att_authorization_status parameter specifies the App Tracking Transparency(ATT) status code. Starting with iOS 14.5, the App Tracking Transparency (ATT) prompt is required in order to access the IDFA identifier. Note: Even if you don't implement the ATT prompt, we require that you pass the ATT authorization status with the value '0', indicating "undetermined". Supported values are: 0 - Undetermined. 1 - Restricted, the user disabled app tracking. 2 - Denied, the user denied authorization. 3 - Authorized, the user granted authorization. Examples: `3`
Event Parameters
Parameter	Description
`n`	`string` The n parameter specifies the Name of the event being tracked. Limitation: max 32 ASCII characters It is recommended to use Singular's standard event naming convention. Example Value: `sng_add_to_cart`

Request Body

Do not provide a request body when calling this method. The request must be sent using the GET method with query parameters.

Request Examples

The following code samples may not represent all supported parameters. When implementing the request be sure to include all required parameters as listed above, and validate that the correct values are being passed before sending data from a production instance. It is advised to uses a unique `i` parameter (application identifier) for development and testing.

PYTHON

import requests

params = {
    'a': 'sdk_key_here',
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'bd': 'Build/13D15',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': 'sng_add_to_cart'
}

response = requests.get('https://s2s.singular.net/api/v1/evt', params=params)
print(response.json())

CURL

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=sdk_key_here" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.singular.app" \
  --data-urlencode "ip=10.1.2.3" \
  --data-urlencode "ve=9.2" \
  --data-urlencode "ma=samsung" \
  --data-urlencode "mo=SM-G935F" \
  --data-urlencode "lc=en_US" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=sng_add_to_cart"

HTTP

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &ma=samsung
    &mo=SM-G935F
    &lc=en_US
    &bd=Build%2F13D15
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=sng_add_to_cart HTTP/1.1
Host: s2s.singular.net
Accept: application/json

JAVA Example

// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/evt";

// Parameters
Map < String, String > params = new HashMap < > ();
params.put("a", "sdk_key_here");
params.put("p", "Android");
params.put("i", "com.singular.app");
params.put("ip", "10.1.2.3");
params.put("ve", "9.2");
params.put("ma", "samsung");
params.put("mo", "SM-G935F");
params.put("lc", "en_US");
params.put("bd", "Build/13D15");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "sng_add_to_cart");

// Build URL with encoded parameters
StringBuilder urlBuilder = new StringBuilder(baseUrl);
urlBuilder.append('?');

for (Map.Entry < String, String > entry: params.entrySet()) {
    if (urlBuilder.length() > baseUrl.length() + 1) {
        urlBuilder.append('&');
    }
    urlBuilder.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
        .append('=')
        .append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}

// Create connection
URL url = new URL(urlBuilder.toString());
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

// Get response
int responseCode = conn.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(conn.getInputStream())
);

String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in .readLine()) != null) {
    response.append(inputLine);
} in .close();

// Check application-level status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

Optional Parameters

The following table lists the optional parameters that this endpoint supports. All of the parameters listed are query parameters.

Optional Parameters
Timestamp Parameters
Parameter	Description
`utime`	`int` The utime parameter specifies the Time of the event in 10 digit UNIX time. Example Value: `1483228800`
Parameter	Description
`umilisec`	`int` The umilisec parameter specifies the of Time of the event in milliseconds 13 digit UNIX time. Example Value: `1483228800000`
Device & Network Parameters
Parameter	Description
`global_properties`	`JSON URL-encoded string` The global_properties parameter accepts a URL-encoded JSON object containing up to 5 key-value pairs. Each key and value can be a maximum length of 200 characters. `{"key1":"value1","key2":"value2"}` The JSON Object must be: Converted to a JSON string and URL-encoded Example Value: `%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D`
Parameter	Description
`use_ip`	`string` The use_ip parameter tells Singular to extract the IP Address from the HTTP request instead of the 'ip' parameter. Pass 'true' to use this feature. Using this parameter prevents Singular from geo-locating the device based on IP Address. You may supply the two-letter country code of the user in the optional 'country' parameter. This parameter is mutually exclusive to the 'ip' parameter. DO NOT use this with the 'ip' parameter. To avoid data rejection, you must supply either 'ip' or the 'use_ip' parameter on the request. Example Value: `true`
Parameter	Description
`country`	`string` The country parameter should contain the ISO 3166-1 alpha-2 two-letter country code of the user at the time of the event execution. This parameter is required only when: The 'ip' parameter is not available If the 'ip' parameter is available, the country will be automatically determined from the IP address, and the 'country' parameter is not needed. Example Value: `US`
Event Parameters
Parameter	Description
`e`	`JSON URL-encoded string` The e parameter specifies custom event attributes in JSON format. `{ "sng_attr_content_id":5581, "sng_attr_content":"XBox", "sng_attr_content_type":"electronics" }` It is highly recommended to use Singular's standard event attribute naming convention. Example Value: `%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`
Revenue Parameters
Parameter	Description
`is_revenue_event`	`string` The is_revenue_event parameter specifies whether the event is a revenue event. You can omit this if the event name is __iap__ or a non-zero amt is provided. Example Value: `true`
Parameter	Description
`amt`	`double` The amt parameter specifies the currency amount. This should be used in conjunction with the 'cur' parameter. Example Value: `2.51`
Parameter	Description
`cur`	`string` The cur parameter specifies the uppercase ISO 4217 three-letter currency code. This should be used in conjunction with the 'amt' parameter. Example Value: `USD`
Parameter	Description
`purchase_receipt` Supported Platforms: Android iOS	`string` The purchase_receipt parameter specifies the receipt received from a purchase. See instructions below on how to retrieve it from Android, iOS How to retrieve the Android purchase receipt. How to retrieve the iOS purchase receipt. Example (iOS): `MIISqwYJKoZI...cNqts0jvcNvPcK7y uj0KhJ9nTTQ54kDKfReihzc6aw==` Example (Android): `%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22%2C%22purchaseTime%22%3A1417113074914%2C%22purchaseState%22%3A0%2C%22purchaseToken%22%3A%22hakfcimbk...%20pM%22%7D`
Parameter	Description
`receipt_signature` Supported Platforms: Android	`string` The receipt_signature parameter specifies the signature used to sign the purchase receipt Example Value: `TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==`
Parameter	Description
`purchase_product_id`	`string` The purchase_product_id parameter specifies the product SKU identifier Example Value: `com.example.product`
Parameter	Description
`purchase_transaction_id`	`string` The purchase_transaction_id parameter specifies the transaction identifier Example (iOS): `380000123004321` Example (Android): `GPA.1234-1234-1234-12345`
Data Privacy
Parameter	Description
`data_sharing_options`	`JSON URL-encoded string` The data_sharing_options parameter specifies the end-user's consent to share information. If set, this value must be persisted and passed on every subsequent 'SESSION' and 'EVENT' request for the user. To indicate that the user consented (opted-in) to share their information pass 'false': `{"limit_data_sharing":false}` If the user refused then pass 'true': `{"limit_data_sharing":true}` The value must be a URL-encoded JSON String. Example Value: `%7B%22limit_data_sharing%22%3Atrue%7D`
Cross Device Support
Parameter	Description
`custom_user_id`	`string` The custom_user_id parameter specifies your internal User ID. Example Value: `123456789abcd`
iOS SkAdNetwork Support
Parameter	Description
`skan_conversion_value` Supported Platforms: iOS	`int` The skan_conversion_value parameter specifies the latest SKAdNetwork conversion value at the time of this event notification (learn more about SKAdNetwork implementation). Example Value: `7`
Parameter	Description
`skan_first_call_timestamp` Supported Platforms: iOS	`int` The skan_first_call_timestamp parameter specifies the Unix timestamp of the first call to the underlying SkAdNetwork API (learn more about SKAdNetwork implementation). Example Value: `1483228800`
Parameter	Description
`skan_last_call_timestamp` Supported Platforms: iOS	`int` The skan_last_call_timestamp parameter specifies the Unix timestamp of the latest call to the underlying SkAdNetwork API at the time of this event notification (learn more about SKAdNetwork implementation). Example Value: `1483228800`

Event Testing

After integrating the server-to-server integration, it is essential to verify that Singular receives data before you go live with a production instance. Refer to our testing guide for more details. At a high level the following steps should be followed:

Obtain your test device Advertising ID and add the ID in the Singular SDK Console.
Open the Singular SDK Console and add the device identifier to start capturing data.
Override the App Identifier with a development App Identifier (com.singular.app.dev) to keep test data and events separate from production data.
Build or Open the App from a terminated state
Validate the App Open is sent to your server with all required Singular data points
Validate your server triggers the Session Notification to the Singular 'launch' endpoint with all required data points.
After a few seconds, the Session event should be displayed in the Singular SDK Console.
Proceed to triggering an Event in the App.
Validate that the Event is sent to your server with all required Singular data points
Validate your server triggers the Event Notification to the Singular 'evt' endpoint with all required data points.
After a few seconds, the Event should be displayed in the Singular SDK Console.
Repeat the test, to validate all events are sent as expected and with the expected values.

Important Verifications

Confirm that the Session Event occurs on App Open or to Foreground and before the Event is received.
Confirm that the Event required data points, match the Session data points.

If you see your Events in the SDK Console, you have completed an end-to-end test of Event handling!

Server-to-Server EVENT Endpoint API Reference