EVENT Endpoint API Reference

Track in-app events and revenue for attribution analysis and campaign optimization using Singular's REST API through server-to-server integration as an alternative to SDK implementation.

Overview

Server-to-Server Use Case

The EVENT endpoint tracks in-app events and revenue for attribution analysis and campaign optimization. New to Server-to-Server? See the S2S Fundamentals guide for core concepts and shared setup.

Supported Capabilities:

Event Attribution: Connect user actions to marketing campaigns
Revenue Tracking: Measure and attribute in-app purchases and transactions
Custom Events: Track any user interaction from registrations to level completions
Event Properties: Attach contextual data to events for deeper analysis

Hybrid Use-Case: In a hybrid integration, the Singular SDK is required and manages session tracking, so the SESSION endpoint is not used. Your server sends events to the EVENT V2 endpoint using the Singular Device ID (SDID) provided by the SDK.

Critical Requirements

Prerequisites:

Session Before Events: SESSION must be established before any event tracking
Sequential Order: Invalid session order results in data inconsistencies and attribution errors

Event Tracking Guidelines

Implement event tracking following Singular's best practices for naming conventions and data structure.

Event Definition

Defining Events

Before implementing S2S integration, define the complete list of events your organization wants to track for campaign performance analysis.

Event planning guide: Defining In-App Events

Event Naming Impact: Event names passed to Singular directly determine how events appear in reports, exports, and postbacks.

Standard Event Naming

Best Practices:

Standard Events: Use Singular's standard event naming convention for streamlined partner integration mapping
English Language: Pass event names in English for compatibility with third-party partners and analytics solutions
Standard Attributes: Use standard event attribute names for event properties

Character Limitations

Length Restrictions:

Event Names: Maximum 32 ASCII characters (32 bytes when converted to UTF-8 for non-ASCII)
Event Attributes: Maximum 500 ASCII characters per attribute key and value

Choosing Your Endpoint

The EVENT endpoint has two versions. Use the accordions below to see the endpoint URL and the required device identifier for each. All other parameters are shared and documented once in Required Parameters and Optional Parameters below.

V2 required as of July 15, 2026. Accounts created on or after July 15, 2026 must use Event Endpoint V2 (SDID-based); V1 is not available for new accounts. Existing customers already integrated on V1 are unaffected. Contact your Singular Customer Success Manager if you want to migrate to V2.

V2 Endpoint (Recommended)

Use V2 for hybrid integrations where the Singular SDK tracks sessions with the Singular Device ID (SDID) and your server sends events using that same SDID. V2 avoids platform-specific device identifiers.

POST https://s2s.singular.net/api/v2/evt

Required identifier:

Parameter Details

sdid

Platforms: iOS, Android, Web, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV
Type: UUIDv4
Singular Device ID obtained from Singular SDK or generated client-side.
Example: 40009df0-d618-4d81-9da1-cbb3337b8dec

iOS/Android: Required for new accounts as of July 15, 2026. For existing accounts, requires account enablement for SDID usage. The SDK callback method provides the SDID after initialization.
Identifier Simplification: Eliminates need for AIFA, ASID, IDFA, IDFV parameters
Web: Retrieved from Singular Web SDK
PC/Console/CTV: Client-generated UUIDv4 representing unique app install
See the SDK documentation.

V1 Endpoint (Legacy)

Use V1 for pure server-side integrations, or hybrid integrations where the Singular SDK does not use the SDID, that rely on platform-specific device identifiers (IDFA, IDFV, AIFA, ASID, etc.).

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

Required identifiers (at least one):

Parameter	Details
`idfa`	Platform: iOS Type: UUIDv4 Identifier for Advertisers (IDFA) enables ad tracking and campaign attribution. ATT requirement: iOS 14.5+ requires user opt-in via the App Tracking Transparency framework. Example: `DFC5A647-9043-4699-B2A5-76F03A97064B` Omit parameter if IDFA unavailable (user denied ATT prompt). Never pass NULL or empty string. Retrieve IDFA
`idfv`	Platform: iOS Type: UUIDv4 Identifier for Vendors (IDFV) remains consistent across all apps from the same vendor. Always required: Must be included regardless of ATT status or IDFA availability. Example: `21DB6612-09B3-4ECC-84AC-B353B0AF1334` Retrieve IDFV
`aifa`	Platform: Android Type: UUIDv4 (Google Play) Google Advertising ID (GAID) enables user-resettable advertising tracking on Android. Example: `8ecd7512-2864-440c-93f3-a3cabe62525b` Required on Google Play devices. Omit on non-Google Play devices. Omit if unavailable—never pass NULL or empty string. Retrieve AIFA
`asid`	Platform: Android Type: UUIDv4 (Google Play) Android App Set ID provides privacy-conscious cross-app tracking for the same developer. Always required: Must be included on Google Play devices regardless of GAID availability. Example: `edee92a2-7b2f-45f4-a509-840f170fc6d9` Omit on non-Google Play devices. Retrieve ASID
`amid`	Platform: Android Type: UUIDv4 (Amazon) Amazon Advertising ID for Amazon devices without Google Play Services. Example: `df07c7dc-cea7-4a89-b328-810ff5acb15d` Required for Amazon Fire devices. Omit if unavailable. Retrieve AMID
`oaid`	Platform: Android Type: UUIDv4 (Chinese OEMs) Open Advertising Identifier (OAID) for Chinese-manufactured devices without Google Play Services (Huawei, Xiaomi, OPPO, etc.). Example: `01234567-89abc-defe-dcba-987654321012` Required for Chinese OEM devices without Google Play. Omit if unavailable. Retrieve OAID
`andi`	Platform: Android Type: String (Non-Google Play) Android ID is a device-generated 64-bit identifier. Restricted use: Prohibited on Google Play devices—use AIFA and ASID instead. Only send if no other identifiers are available and the app is not distributed via Google Play. Retrieve ANDI Example: `fc8d449516de0dfb`

Required Parameters

All EVENT requests must include these required parameters in addition to device identifiers.

Parameter Format: All parameters must be sent as application/x-www-form-urlencoded data in the request body using the POST method. Requests must include the header Content-Type: application/x-www-form-urlencoded . Do not send parameters in a JSON request body.

API Authentication

Parameter	Details
`a`	Type: String Singular SDK Key for API authentication. Retrieve from: Singular UI → Main Menu → Developer Tools . Important: Do not use the Reporting API Key. Requests will be rejected. Example: `sdkKey_afdadsf7asf56`

Device Parameters

Parameter	Details
`p`	Type: String Platform of the application. Allowed values (case-sensitive): Example: `Android` Android iOS Web PC Xbox Playstation Nintendo MetaQuest CTV
`ip`	Type: String Example: `172.58.29.235` Public IPv4 address of the device. IPv6 is supported, but IPv4 is recommended for attribution compatibility with ad networks.
`ve`	Type: String Example: `9.2` OS version of the device at session time.
`ma`	Platform: iOS, Android Type: String Device make (manufacturer name). Must be used with `mo` (model). Retrieve Device Make Example: `Samsung` , `LG` , `Apple`
`mo`	Platform: iOS, Android Type: String Device model. Must be used with `ma` (make). Retrieve Device Model Example: `iPhone 4S` , `Galaxy SIII`
`lc`	Platform: iOS, Android Type: String IETF locale tag—two-letter language and country code separated by an underscore. Retrieve Device Locale Example: `en_US`
`bd`	Platform: iOS, Android Type: String Device build identifier, URL-encoded. Retrieve Device Build Example: `Build%2F13D15`

Application Parameters

Parameter Details

i

Type: String
App identifier (case-sensitive).
Example: com.singular.app

Android: Package Name (e.g., com.singular.app )
iOS: Bundle ID (e.g., com.singular.app )
PC/Console: Your designated identifier

app_v

Type: String
Example: 1.2.3

Application version.

att_authorization_status

Platform: iOS
Type: Integer
App Tracking Transparency (ATT) status code (iOS 14.5+).
Status values:

0 - Undetermined (prompt not shown)
1 - Restricted (device-level tracking disabled)
2 - Denied (user denied authorization)
3 - Authorized (user granted authorization)

Always required: Even if ATT is not implemented, pass 0 (undetermined).

Example: 3

Event Parameters

Parameter	Details
`n`	Type: String Name of the event being tracked. Example: `sng_add_to_cart` Maximum 32 ASCII characters (32 bytes for UTF-8) Recommended: Use standard event naming convention

Optional Parameters

Optional parameters enhance event tracking with additional context and functionality.

Timestamp Parameters

Parameter	Details
`utime`	Type: Integer 10-digit Unix timestamp of event. Example: `1483228800`
`umilisec`	Type: Integer 13-digit Unix timestamp with milliseconds. Example: `1483228800000`

Event Attributes

Partner Conversion API support: To forward these events to ad network partners through Singular's Conversion API integrations, include the standard optional event attributes (hashed first-party data such as eventId and ehash ). See Standard Event Attributes for Conversion API Integrations .

Parameter Details

e

Type: JSON
JSON URL-encoded string specifying custom event attributes.
JSON Structure:
URL-Encoded Example:

{
  "sng_attr_content_id": 5581,
  "sng_attr_content": "XBox",
  "sng_attr_content_type": "electronics"
}

Recommended: Use standard attribute naming convention
Maximum 500 ASCII characters per attribute key and value

%7B%22sng_attr_content_id%22%3A5581%2C%22sng_attr_content%22%3A%22XBox%22%2C%22sng_attr_content_type%22%3A%22electronics%22%7D

global_properties

Type: JSON
JSON URL-encoded object containing custom key-value pairs applied globally to event.
Limits:
JSON: {"key1":"value1","key2":"value2"}
URL-Encoded: %7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D

Maximum 5 key-value pairs
Maximum 200 characters per key and value

Network Parameters

Parameter	Details
`use_ip`	Type: Boolean Instructs Singular to extract the IP address from the HTTP request instead of the `ip` parameter. Limitations: Prevents IP-based geolocation by Singular. Supply a two-letter country code via the `country` parameter. Mutually exclusive with the `ip` parameter—do not use both. Must supply either `ip` or `use_ip` to avoid data rejection. Example: `true`
`country`	Type: String ISO 3166-1 alpha-2 two-letter country code. Required when: IP address is not available or `use_ip=true` . Example: `US`
`ua`	Type: String URL-encoded User Agent string. Raw: `Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...` Example: `Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...`
`c`	Platform: iOS, Android Type: String Network connection type. Allowed values: `wifi` , `carrier` Example: `wifi`
`cn`	Platform: iOS, Android Type: String Example: `Comcast` Carrier name of the internet provider.

Data Privacy

Parameter Details

data_sharing_options

Type: JSON
JSON URL-encoded end-user consent for data sharing. Must persist and be passed on all subsequent SESSION and EVENT requests.
User consented (opted-in):
User refused (opted-out):
Example: %7B%22limit_data_sharing%22%3Atrue%7D

{"limit_data_sharing":false}

{"limit_data_sharing":true}

dnt

Platform: iOS, Android
Type: Integer
Do Not Track status.
Example: 0

1 - Do Not Track enabled
0 - Do Not Track disabled

dntoff

Platform: iOS, Android
Type: Integer
Indicates if Do Not Track is OFF.
Example: 1

0 - Do Not Track enabled (OFF=false)
1 - Do Not Track disabled (OFF=true)

Cross-Device Support

Parameter Details

custom_user_id

Type: String
Your internal user ID for cross-device tracking.

No PII: Do not pass personally identifiable information. Use a hashed or otherwise anonymized internal identifier, not raw email addresses, phone numbers, or names.

Example: 123456789abcd

SKAdNetwork Support

Parameter	Details
`skan_conversion_value`	Platform: iOS Type: Integer Latest SKAdNetwork conversion value at event time. Learn more: SKAdNetwork Implementation Example: `7`
`skan_first_call_timestamp`	Platform: iOS Type: Integer Unix timestamp of first call to SKAdNetwork API. Example: `1483228800`
`skan_last_call_timestamp`	Platform: iOS Type: Integer Unix timestamp of most recent call to SKAdNetwork API at event time. Example: `1483228800`

Revenue Tracking

Track in-app purchases and revenue events with proper validation and currency handling.

Required Revenue Parameters

Basic Revenue Tracking

Minimum required parameters for revenue event tracking when performing your own revenue validation.

Best Practice: Validate revenue events with App Stores on your server-side before sending event request to Singular. If performing own validation, only these parameters required.

Parameter Details

is_revenue_event

Type: Boolean
Marks the event as a revenue event for Revenue metrics.
Example: true

Optional. An event is also treated as revenue automatically when the event name is __iap__ / __iapauto__ , or when an amt parameter is present.
Setting is_revenue_event=false does not prevent revenue treatment when amt is included.

amt

Type: Number
Currency amount of transaction.
Example: 2.51

Use in conjunction with cur parameter

cur

Type: String
ISO 4217 three-letter uppercase currency code.
Example: USD

Use in conjunction with amt parameter

Note: Sending the amt parameter causes the event to be processed as a revenue event regardless of the is_revenue_event value, including is_revenue_event=false . If you do not want an event treated as a revenue event, omit the amt parameter. To mark a revenue event that has no amount, send is_revenue_event=true .

Revenue Validation Parameters

Singular-Validated Revenue

Optional parameters for Singular to perform server-side revenue validation with App Stores.

Validation Requirements:

Required if relying on Singular for revenue validation with App Stores
Confirm correct syntax of purchase receipt and signature values
Incorrect formatting causes Singular to block revenue and generate __iapinvalid__ event

Parameter	Details
`purchase_receipt`	Platform: iOS, Android Type: JSON Receipt received from purchase transaction. Example (iOS): Example (Android, URL-encoded): Android: Google Play Billing Library Purchase object iOS: StoreKit app receipt `MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==` `%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22...`
`receipt_signature`	Platform: Android Type: String Signature used to sign purchase receipt (Android only). Example: `TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==`
`purchase_product_id`	Type: String Product SKU identifier. Example: `com.example.product`
`purchase_transaction_id`	Type: String Transaction identifier. Example (iOS): `380000123004321` Example (Android): `GPA.1234-1234-1234-12345`

Ad Revenue Tracking

Track impression-level ad monetization revenue from mediation platforms (for example, AdMob, AppLovin MAX, or ironSource) by sending a standard EVENT with a fixed event name and ad-monetization attributes. Ad revenue uses the same EVENT endpoint documented above.

Mediation Platform Data: Collect the required ad-revenue attributes directly from your mediation platform SDK. See the Ad Revenue SDK Guide for the attributes each mediation platform provides.

Ad Monetization Revenue

In addition to the standard required parameters (authentication, device, and application), ad-revenue events require the following.

Parameter	Details
`n`	Type: String Name of the event being tracked. Required event name for ad revenue: `__ADMON_USER_LEVEL_REVENUE__` Event name must be ALL UPPERCASE with underscores Maximum 32 ASCII characters
`is_admon_revenue`	Type: Boolean Identifies the event as an ad-monetization revenue event for Ad Revenue metrics. Example: `true` Pass `true` for this event
`is_revenue_event`	Type: Boolean Identifies the event as a revenue event for Revenue metrics. Example: `true` Pass `true` for this event
`amt`	Type: Number Currency amount of impression revenue. Example: `0.00782` Use in conjunction with `cur` parameter
`cur`	Type: String ISO 4217 three-letter uppercase currency code. Example: `USD` Use in conjunction with `amt` parameter
`e`	Type: JSON JSON URL-encoded string specifying ad-monetization attributes from the mediation platform. Required attribute: `ad_platform` — (required) Name of the ad network Optional attributes: `ad_mediation_platform` `ad_type` `ad_group_type` `ad_impression_id` `ad_placement_name` `ad_unit_id` `ad_unit_name` `ad_group_id` `ad_group_name` `ad_group_priority` `ad_placement_id` JSON structure: `{ "ad_platform": "AdMob", "ad_mediation_platform": "admob.AdMobAdapter", "ad_unit_id": "ca-app-pub-6325336052/44923540" }` URL-encoded example: `%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%5C%2F44923540%22%7D` Note: Omit attributes without values.

Request Examples

Sample code demonstrates EVENT endpoint integration across multiple programming languages.

Example Disclaimer: Code samples may not include all required parameters. Validate complete parameter list before production implementation. Use unique i (app identifier) for development/testing.

Python Example

import requests

url = 'https://s2s.singular.net/api/v1/evt'
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
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.post(url, data=params, headers=headers)
print(response.json())

cURL Example

curl -X POST "https://s2s.singular.net/api/v1/evt" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --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 Example

POST /api/v1/evt HTTP/1.1
Host: s2s.singular.net
Content-Type: application/x-www-form-urlencoded
Accept: application/json

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

Java Example

// Endpoint
String endpoint = "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 form-urlencoded body
StringBuilder form = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
    if (form.length() > 0) form.append('&');
    form.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
        .append('=')
        .append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
byte[] body = form.toString().getBytes(StandardCharsets.UTF_8);

// Create connection
URL url = new URL(endpoint);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setRequestProperty("Accept", "application/json");

// Write body
try (OutputStream os = conn.getOutputStream()) {
    os.write(body);
}

// 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();

System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
conn.disconnect();

Response Codes & Errors

EVENT endpoint returns HTTP status codes and JSON responses indicating request success or failure.

Complete error documentation: S2S Response Codes & Error Handling

Testing & Validation

Verify S2S event integration before production deployment using Singular SDK Console for real-time data validation.

Testing Procedure

End-to-End Validation

Register Test Device: Obtain device advertising ID and add to Singular SDK Console
Enable Console Logging: Add device identifier in SDK Console to capture test data
Use Development App ID: Override app identifier with development version (e.g., com.singular.app.dev ) to separate test from production data
Build and Launch: Build or open app from terminated state
Validate Client Data: Confirm app sends all required Singular data points to your server
Verify Session: Confirm your server sends SESSION request to https://s2s.singular.net/api/v1/launch with all required parameters
Check SDK Console (Session): Within seconds, SESSION event should appear in SDK Console

SDK Console Session Event

Event Testing

Trigger Event: Proceed to triggering an event in the app
Validate Event Data: Confirm event sent to your server with all required Singular data points
Verify Server Request: Confirm your server sends the EVENT request to your endpoint (V2 https://s2s.singular.net/api/v2/evt or V1 https://s2s.singular.net/api/v1/evt ) with all required parameters.
Check SDK Console (Event): Within seconds, EVENT should appear in SDK Console
Repeat Tests: Validate all events sent with expected values

SDK Console Event

Critical Verifications:

Confirm SESSION event occurs on app open/foreground BEFORE EVENT received
Confirm EVENT required data points match SESSION data points

Success Indicator: If events appear in SDK Console, you've completed successful end-to-end event integration test!

Additional Resources

Testing Documentation

Comprehensive testing guide: S2S Integration Testing Guide

Server-to-Server - EVENT Endpoint API Reference

EVENT Endpoint API Reference

Overview

Server-to-Server Use Case

Critical Requirements

Event Tracking Guidelines

Event Definition

Defining Events

Standard Event Naming

Character Limitations

Choosing Your Endpoint

Required Parameters

API Authentication

Device Parameters

Application Parameters

Event Parameters

Optional Parameters

Timestamp Parameters

Event Attributes

Network Parameters

Data Privacy

Cross-Device Support

SKAdNetwork Support

Revenue Tracking

Required Revenue Parameters

Basic Revenue Tracking

Revenue Validation Parameters

Singular-Validated Revenue

Ad Revenue Tracking

Ad Monetization Revenue

Request Examples

Python Example

cURL Example

HTTP Example

Java Example

Response Codes & Errors

Testing & Validation

Testing Procedure

End-to-End Validation

Event Testing

Additional Resources

Testing Documentation