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

EVENT API enables in-app event tracking where apps forward user interaction data to your backend, which transmits to Singular's servers for event attribution and revenue analytics reporting.

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

Data Flow Architecture

Server-to-server event tracking follows a four-step data transmission process.

Client Collection: App collects event data and device identifiers
Server Transmission: App forwards event data to your backend server
Device Graph Query: Server retrieves or updates device details from Singular device graph
Event API Call: Server sends event to Singular REST API endpoint

Event Data Flow Diagram

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

Integration Constraints:

Real-time Processing: Requests processed individually—no batch support
Chronological Events: Events must be sent in order they occurred
No Deduplication: Singular does not deduplicate data—implement server-side deduplication to prevent duplicates
Data Permanence: Device-level data cannot be deleted after ingestion—validate before sending

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

API Endpoint Selection

Singular provides two EVENT endpoint versions optimized for different integration architectures.

Endpoint Selection: Choose endpoint based on your integration architecture and device identifier strategy. Use-case determines correct endpoint.

Event Endpoint V1

V1 Use Cases

Use Event Endpoint V1 for integrations relying on platform-specific device identifiers (IDFA, IDFV, AIFA, ASID, etc.).

Recommended For:

Pure Server-Side: Server-side integrations without Singular SDK implementation
Hybrid (Non-SDID): Hybrid integrations where Singular SDK does not use Singular Device ID (SDID)

Endpoint URL:

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

Event Endpoint V2

V2 Use Cases

Use Event Endpoint V2 for hybrid integrations where Singular SDK tracks sessions using SDID and server sends events using same SDID.

Recommended For:

Hybrid (SDID-Based): Singular SDK tracks sessions with SDID and server-side events use same SDID
Simplified Identifiers: Implementations avoiding platform-specific device identifiers (IDFA, AIFA, etc.)

Endpoint URL:

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

Account Enablement: V2 endpoint requires Singular account configuration for SDID usage. Contact your Solution Engineer or CSM for enablement.

Required Device Identifiers

Device identifier requirements vary by endpoint version and platform. Review platform-specific requirements below.

V1 Endpoint Identifiers

Platform-Specific Identifiers

Event Endpoint V1 requires platform-specific advertising identifiers based on device operating system and app distribution method.

Parameter	Platform	Description
`idfa`	iOS	Identifier for Advertisers (IDFA) enables ad tracking and campaign attribution. ATT Requirement: iOS 14.5+ requires user opt-in via App Tracking Transparency Omit parameter if IDFA unavailable (user denied ATT) Never pass NULL or empty string Retrieve IDFA Example:`DFC5A647-9043-4699-B2A5-76F03A97064B`
`idfv`	iOS	Identifier for Vendors (IDFV) remains consistent across all apps from same vendor. Always Required: Must be included regardless of ATT status or IDFA availability Retrieve IDFV Example:`21DB6612-09B3-4ECC-84AC-B353B0AF1334`
`aifa`	Android (Google Play)	Google Advertising ID (GAID) enables user-resettable advertising tracking. Required on Google Play devices Omit on non-Google Play devices Never pass NULL or empty string Retrieve AIFA Example:`8ecd7512-2864-440c-93f3-a3cabe62525b`
`asid`	Android (Google Play)	Android App Set ID provides privacy-conscious cross-app tracking for same developer. Always Required: Must be included on Google Play devices regardless of GAID availability Retrieve ASID Example:`edee92a2-7b2f-45f4-a509-840f170fc6d9`
`amid`	Android (Amazon)	Amazon Advertising ID for Amazon Fire devices without Google Play Services. Required for Amazon devices Retrieve AMID Example:`df07c7dc-cea7-4a89-b328-810ff5acb15d`
`oaid`	Android (Chinese OEMs)	Open Advertising Identifier (OAID) for Chinese-manufactured devices without Google Play Services. Required for Huawei, Xiaomi, OPPO, Vivo devices without Google Play Retrieve OAID Example:`01234567-89abc-defe-dcba-987654321012`
`andi`	Android (Non-Google Play)	Android ID is device-generated 64-bit identifier. Restricted Use: Prohibited on Google Play devices. Only use if no other identifiers available and app not distributed via Google Play. Retrieve ANDI Example: `fc8d449516de0dfb`
`sdid`	iOS, Android, Web, PC, Console, CTV	Anonymized Singular Device ID generated by the customer Web: Obtained from Singular Web SDK PC/Console: Client-generated UUIDv4 representing unique app install Retrieve SDID Example:`40009df0-d618-4d81-9da1-cbb3337b8dec`

V2 Endpoint Identifiers

SDID-Only Requirement

Event Endpoint V2 requires only Singular Device ID (SDID) for all platforms, simplifying device identification.

Parameter Description

sdid

Platforms: iOS, Android, Web, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV

Singular Device ID obtained from Singular SDK or generated client-side.

iOS/Android: Requires account enablement for SDID usage—SDK callback method provides 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
Retrieve SDID

Example:40009df0-d618-4d81-9da1-cbb3337b8dec

Required Parameters

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

Parameter Format: All parameters must be passed as URL query parameters using GET method. Do not send parameters in JSON request body.

API Authentication

Parameter Type Description

a

string

Singular SDK Key for API authentication.

Retrieve From: Singular UI → Main Menu → Developer Tools

Important: Do not use Reporting API Key—requests will be rejected.

Example: sdkKey_afdadsf7asf56

Device Parameters

Parameter Description

p

Platform of the application (case-sensitive).

Allowed Values: Android, iOS, Web, PC, Xbox, Playstation, Nintendo, MetaQuest, CTV

Example: Android

ip

Public IPv4 IP address of device. IPv6 supported but IPv4 recommended for attribution compatibility.

Example: 172.58.29.235

ve

OS version of device at event time.

Example: 9.2

Application Parameters

Parameter Description

i

App identifier (case-sensitive).

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

Example: com.singular.app

att_authorization_status
iOS

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 not implemented, pass 0 (undetermined).

Example: 3

Event Parameters

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

Optional Parameters

Optional parameters enhance event tracking with additional context and functionality.

Timestamp Parameters

Parameter	Type	Description
`utime`	`int`	10-digit Unix timestamp of event. Example: `1483228800`
`umilisec`	`int`	13-digit Unix timestamp with milliseconds. Example: `1483228800000`
`ma` iOS, Android	`string`	Device make (manufacturer name). Must be used with `mo` (model). Retrieve Device Make Examples: `Samsung`, `LG`, `Apple`
`mo` iOS, Android	`string`	Device model. Must be used with `ma` (make). Retrieve Device Model Examples: `iPhone 4S`, `Galaxy SIII`
`lc` iOS, Android	`string`	IETF locale tag—two-letter language and country code separated by underscore. Retrieve Device Locale Example: `en_US`
`bd` iOS, Android	`string`	Device build identifier, URL-encoded. Retrieve Device Build Example: `Build%2F13D15`

Event Attributes

Parameter Description

e

JSON URL-encoded string specifying custom event attributes.

JSON Structure:

{
  "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

URL-Encoded Example:

%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

JSON URL-encoded object containing custom key-value pairs applied globally to event.

Limits:

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

JSON:{"key1":"value1","key2":"value2"}

URL-Encoded:%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D

Network Parameters

Parameter Description

use_ip

Instructs Singular to extract IP address from HTTP request instead of ip parameter.

Limitations:

Prevents IP-based geolocation by Singular
Supply two-letter country code via country parameter
Mutually exclusive with ip parameter
Must supply either ip or use_ip

Example: true

country

ISO 3166-1 alpha-2 two-letter country code.

Required When: IP address not available or use_ip=true

Example: US

Data Privacy

Parameter Description

data_sharing_options

JSON URL-encoded end-user consent for data sharing. Must persist and pass on all subsequent EVENT requests.

User Consented (Opted-In):

{"limit_data_sharing":false}

User Refused (Opted-Out):

{"limit_data_sharing":true}

URL-Encoded Example:%7B%22limit_data_sharing%22%3Atrue%7D

Cross-Device Support

Parameter Description

custom_user_id

Your internal user ID for cross-device tracking.

Example: 123456789abcd

SKAdNetwork Support

Parameter Description

skan_conversion_value
iOS

Latest SKAdNetwork conversion value at event time.

Learn more: SKAdNetwork Implementation

Example: 7

skan_first_call_timestamp
iOS

Unix timestamp of first call to SKAdNetwork API.

Example: 1483228800

skan_last_call_timestamp
iOS

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 Type Description

is_revenue_event

string

Specifies whether event is revenue event.

Can be omitted if event name is __iap__ or non-zero amt provided

Example: true

amt

double

Currency amount of transaction.

Use in conjunction with cur parameter

Example: 2.51

cur

string

ISO 4217 three-letter uppercase currency code.

Use in conjunction with amt parameter

Example: USD

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

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

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 Example

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 Example

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 status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
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 EVENT request to 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

Data Flow Architecture

Critical Requirements

Event Tracking Guidelines

Event Definition

Defining Events

Standard Event Naming

Character Limitations

API Endpoint Selection

Event Endpoint V1

V1 Use Cases

Event Endpoint V2

V2 Use Cases

Required Device Identifiers

V1 Endpoint Identifiers

Platform-Specific Identifiers

V2 Endpoint Identifiers

SDID-Only Requirement

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

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