SESSION Endpoint API Reference

Track user sessions and enable attribution for app installs, re-engagement, and retention metrics through Singular's REST API using server-to-server integration as an alternative to SDK implementation.

Overview

Server-to-Server Use Case

Singular REST API enables direct server-to-server integration where apps forward device-specific data to your backend, which transmits to Singular's servers for attribution processing and analytics reporting.

Supported Capabilities:

• Install Attribution: First-touch attribution to marketing campaigns
• Re-engagement Attribution: Multi-touch attribution for returning users
• Retention Metrics: Session-based engagement tracking
• Event Tracking: Custom in-app event measurement

Data Flow Architecture

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

1. Client Collection: App collects required device and application data
2. Server Transmission: App forwards collected data to your backend server
3. Singular API Call: Your server sends data to Singular REST API endpoint
4. Response Handling: Your server receives and processes Singular's response

Key Considerations

Integration Benefits:

• Flexibility: Complete control over data collection and transmission timing
• Feature Parity: Supports all SDK functionality when proper data provided
• Custom Implementation: Adapt integration to specific backend architecture

Session Management

SESSION endpoint notifies Singular of app open events to initialize user sessions for attribution and tracking.

When to Send Sessions

Session Triggers

Send SESSION requests for these app lifecycle events:

• Fresh Installations: First app launch after install
• Terminated State Launch: App opens from fully closed state
• Background to Foreground: App returns to foreground after timeout period (recommended: 60 seconds)

Session Timeout Logic

Implement session timeout to prevent excessive SESSION requests during brief app backgrounding.

Recommended Implementation:

• Timeout Duration: 60 seconds (1 minute)
• Foreground < Timeout: Do not send SESSION if app returns to foreground within timeout period
• Foreground > Timeout: Send SESSION if app remains backgrounded beyond timeout period
• App Lifecycle Tracking: Use app lifecycle events and timers to manage session state

Attribution Processing

Session-Based Attribution

Singular processes SESSION requests to determine attribution type and trigger appropriate workflows.

Learn more: Re-engagement Attribution FAQ

Event Order Requirements

Session and event timing directly impacts attribution accuracy and data quality.

Advanced Options

Extended Functionality

Singular S2S integration supports advanced capabilities requiring additional SESSION parameters.

API Endpoint Specification

SESSION endpoint accepts GET requests with query parameters containing device, application, and attribution data.

Endpoint URL

Base URL and Method

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

Request Format:

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

Required Parameters

All SESSION requests must include these required parameters with proper values and formatting.

API Authentication

SDK Key

These are shared S2S parameters defined once in S2S Fundamentals .

Device Identifiers

Platform-Specific Identifiers

These are shared S2S parameters defined once in S2S Fundamentals .

Device Parameters

Device Information

These are shared S2S parameters defined once in S2S Fundamentals .

Application Parameters

App Information

App identifier ( i ), app_v , and att_authorization_status are shared parameters. See Application Parameters in S2S Fundamentals .

Fraud Prevention Parameters

Install Source Validation

Deep Linking Parameters

Deep Link Support

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

{
  "status":"ok",
  "resolved_singular_link":"https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

Advanced Attribution Parameters

Platform Attribution Enhancement

{
   "installBeginTimestampSeconds":"1568939453",
   "referrer":"utm_source=google-play&utm_medium=organic",
   "clickTimestampSeconds":"0",
   "referrer_source":"service",
   "current_device_time":"1568944524"
}

{
   "install_time_epoch_seconds":"1568939453",
   "install_referrer":"utm_source=google-play&utm_medium=organic"
}

{
  "install_referrer": {
    "utm_source":"apps.facebook.com",
    "utm_campaign": "fb4a",
    "utm_content": {
      "source":{
        "data":"c7e6b890bf18a059c2185650bdb1af3dced7...",
        "nonce":"24859720343e2381daee9f39ae61"
        },
      "app":533744218636280,
      "t":1731181327
      },
    "is_ct":1,
    "actual_timestamp":1731181444
  }
}

Optional Parameters

Optional parameters enhance tracking capabilities and support advanced features.

Timestamp Parameters

Network & Location Parameters

These are shared S2S parameters defined once in S2S Fundamentals .

Custom Properties

Uninstall Tracking Support

Data Privacy Parameters

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

Google Ads ICM Support (Beta)

Request Examples

Sample code demonstrates SESSION 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',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'install': 'true',
    'n': 'MyCoolAppName',
    'bd': 'Build/13D15',
    'app_v': '1.2.3',
    'openuri': 'myapp://home/page?queryparam1=value1',
    'ddl_enabled': 'true',
    'install_source': 'com.android.vending',
    'install_time': 1510040127,
    'update_time': 1510090877
}

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

curl -G "https://s2s.singular.net/api/v1/launch" \
  --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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "install=true" \
  --data-urlencode "n=MyCoolAppName" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "app_v=1.2.3" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1" \
  --data-urlencode "ddl_enabled=true" \
  --data-urlencode "install_source=com.android.vending" \
  --data-urlencode "install_time=1510040127" \
  --data-urlencode "update_time=1510090877"

GET /api/v1/launch
    ?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
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &install=true
    &n=MyCoolAppName
    &bd=Build%2F13D15
    &app_v=1.2.3
    &openuri=myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1
    &ddl_enabled=true
    &install_source=com.android.vending
    &install_time=1510040127
    &update_time=1510090877 HTTP/1.1
Host: s2s.singular.net
Accept: application/json

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

// 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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("install", "true");
params.put("n", "MyCoolAppName");
params.put("bd", "Build/13D15");
params.put("app_v", "1.2.3");
params.put("openuri", "myapp://home/page?queryparam1=value1");
params.put("ddl_enabled", "true");
params.put("install_source", "com.android.vending");
params.put("install_time", "1510040127");
params.put("update_time", "1510090877");

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

SESSION 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 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. Launch App: Open app from terminated state to trigger session
5. Validate Client Data: Confirm app sends all required Singular data points to your server
6. Verify Server Request: Confirm your server sends SESSION request to https://s2s.singular.net/api/v1/launch with all required parameters
7. Check SDK Console: Within seconds, SESSION event should appear in SDK Console
8. Repeat Tests: Validate SESSION triggers on every app entry and foreground operation

Additional Resources

Testing Documentation

Comprehensive testing guide: S2S Integration Testing Guide