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.

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

Critical Requirements

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

Character Limitations

API Endpoint Selection

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

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

Web (p=Web) Variant

Web integrations use this same EVENT endpoint with p=Web . There is no web SESSION call: the first __PAGE_VISIT__ event with conversion_event=true establishes the attribution touchpoint in place of a launch.

Web-Specific Parameters

These parameters apply when p=Web . Shared parameters ( a , i , ip , sdid , custom_user_id ) are defined in S2S Fundamentals .

Web click IDs: pass partner click IDs ( ScCid , ttclid , gclid / gbraid / wbraid , dclid , fbclid , rdt_uuid ) inside the event e parameter.

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.

These are shared S2S parameters defined once in S2S Fundamentals .

V2 Endpoint Identifiers

SDID-Only Requirement

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

Required Parameters

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

API Authentication

These are shared S2S parameters defined once in S2S Fundamentals .

Device Parameters

These are shared S2S parameters defined once in S2S Fundamentals .

Application Parameters

These are shared S2S parameters defined once in S2S Fundamentals .

Event Parameters

Optional Parameters

Optional parameters enhance event tracking with additional context and functionality.

Timestamp Parameters

Event Attributes

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

%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

Network Parameters

These are shared S2S parameters defined once in S2S Fundamentals .

Data Privacy

These are shared S2S parameters defined once in S2S Fundamentals .

Cross-Device Support

These are shared S2S parameters defined once in S2S Fundamentals .

SKAdNetwork Support

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.

Revenue Validation Parameters

Singular-Validated Revenue

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

MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==

%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22...

TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==

Request Examples

Sample code demonstrates EVENT endpoint integration across multiple programming languages.

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

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

// 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

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

Event Testing

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

Additional Resources

Testing Documentation

Comprehensive testing guide: S2S Integration Testing Guide