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.

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

Session Data Flow Diagram

Key Considerations

Critical Requirements:

Real-time Processing: Requests processed individually—no batch support
Sequential Order: Events must be sent chronologically
No Deduplication: Singular does not deduplicate data—implement server-side deduplication
Data Permanence: Device-level data cannot be deleted after ingestion—validate before sending
Session First: Session must be established before any event tracking

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

Deep Link Support: Always send SESSION for app opens via deep links, Universal Links, or App Links with the openuri parameter populated, regardless of timeout status.

Attribution Processing

Session-Based Attribution

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

Session Type	Singular Processing	Attribution Result
First Session (New Install)	Install attribution process triggered	Attributes install to marketing campaign
Re-engagement Qualified	Re-engagement attribution process triggered	Attributes user return to campaign or deep link
Standard Session	Session recorded for retention tracking	Counts toward user activity and engagement metrics

Learn more: Re-engagement Attribution FAQ

Event Order Requirements

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

Critical Ordering Rules:

Session Before Events: Single SESSION must be received before any events for that session
Real-time Event Transmission: In-app events must be sent in real-time after their respective session
Sequential Processing: Invalid session order results in data inconsistencies and attribution errors

Advanced Options

Extended Functionality

Singular S2S integration supports advanced capabilities requiring additional SESSION parameters.

Advanced Features: Review Advanced S2S Options for deep linking, SKAdNetwork, and cross-device tracking requirements.

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

Request Body: Do not provide request body—all parameters must be sent as URL query parameters using GET method.

Required Parameters

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

API Authentication

SDK Key

Parameter Type Description

a

string

Singular SDK Key for API authentication.

Retrieve From: Singular UI → Main Menu → Developer Tools

Example: sdkKey_afdadsf7asf56

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

Device Identifiers

Platform-Specific Identifiers

Device identifiers vary by platform and availability. Include all applicable identifiers for your platform.

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 framework Omit parameter if IDFA unavailable (user denied ATT prompt) 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 on Android. Required on Google Play devices Omit on non-Google Play devices Omit if unavailable—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 Omit on non-Google Play devices Retrieve ASID Example: `edee92a2-7b2f-45f4-a509-840f170fc6d9`
`amid`	Android (Amazon)	Amazon Advertising ID for Amazon devices without Google Play Services. Required for Amazon Fire devices Omit if unavailable Retrieve AMID Example: `df07c7dc-cea7-4a89-b328-810ff5acb15d`
`oaid`	Android (Chinese OEMs)	Open Advertising Identifier (OAID) for Chinese-manufactured devices without Google Play Services (Huawei, Xiaomi, OPPO, etc.). Required for Chinese OEM devices without Google Play Omit if unavailable 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—use AIFA and ASID instead. Only send if no other identifiers available and app not distributed via Google Play. Retrieve ANDI Example: `fc8d449516de0dfb`
`sdid`	PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV	Singular Device ID is client-generated UUIDv4 representing unique app install. Primary Identifier: Only device identifier used for PC and console applications Example: `40009df0-d618-4d81-9da1-cbb3337b8dec`
`sing`	Enterprise Only	Client-defined identifier for special use cases where standard identifiers unavailable. Restricted: Enterprise customers only—must be enabled by Singular Solution Engineer on per-app basis. Contact CSM for more information. Example: `da534a95-1b1b-47d4-94b6-07955ec85177`

Device Parameters

Device Information

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

Application Parameters

App Information

Parameter	Description
`i`	App identifier (case-sensitive). Android: Package Name (e.g., `com.singular.app`) iOS: Bundle ID (e.g., `com.singular.app`) PC/Console: Your designated identifier Example: `com.singular.app`
`app_v`	Application version. Example: `1.2.3`
`install`	Indicates if session represents first session after install or reinstall. `true` - First session after fresh install/reinstall `false` - Subsequent session (app already installed) Required for: Reinstall tracking capabilities Example: `true`
`install_time` iOS, Android	Unix timestamp of first app install. Example: `1510040127`
`update_time` iOS, Android	Unix timestamp of last app update. Example: `1510040127`
`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`

Fraud Prevention Parameters

Install Source Validation

Parameter Description

install_source
Android, PC

Install source package name or store identifier.

Android: Install Source Package Name

Android Example: com.android.vending (Google Play Store)

PC Supported Stores:

steam
epic
microsoftstore
humblestore
gog
selfdistributed

install_receipt
iOS

Base64-encoded iOS install receipt for fraud validation.

Example (truncated): MIJF9wYJKoZIhvcNAQcCoIJF6DCCReQCAQExCzAJBgUrDgMCGgUAMII1m...

Deep Linking Parameters

Deep Link Support

Parameter Description

openuri
iOS, Android

URL-encoded deep link, Universal Link, or App Link that opened the app.

Original URL: myapp://home/page?queryparam1=value1&queryparam2=value2

Encoded Example: myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1%26queryparam2%3Dvalue2

ddl_enabled
iOS, Android

Indicates if app expects deferred deep link URL in response.

true - Expect deferred deep link in response
false - Do not expect deferred deep link

Example Response:

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

singular_link_resolve_required
iOS, Android

Requests resolution of Singular short link to long link. Must be used with openuri containing Singular short link.

true - Return expanded long link
false - Do not resolve link

Example Response:

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

Parameter Description

install_ref
Android (Google Play)

JSON URL-encoded Google Install Referrer information. Provides most accurate attribution for Android installs.

JSON Structure:

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

Required For:

Facebook user-level exports
Data Destination sharing
Postback accuracy

More info: Google Install Referrer Documentation

URL-Encoded Example: %7B%22installBeginTimestampSeconds%22%3A%221568939453%22...

meta_ref
Android (Google Play)

As of June 18, 2025: Meta Advanced Mobile Measurement (AMM) removes need for Meta Install Referrer implementation. Not recommended if AMM enabled.

JSON URL-encoded Meta Install Referrer for granular user-level attribution data.

JSON Structure:

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

Learn more: Meta Referrer FAQ

attribution_token
iOS

Apple Search Ads attribution token from AdServices framework (iOS 14.3+).

Retrieve Using: attributionToken() on first app launch after install/reinstall.

Example (truncated): KztLg%2FIkNsWDMuBMOU%2BySnkPU5myJb4OFmeaMUE%2BTqQJP...

Optional Parameters

Optional parameters enhance tracking capabilities and support advanced features.

Timestamp Parameters

Parameter Description

utime

10-digit Unix timestamp of session.

Example: 1483228800

umilisec

13-digit Unix timestamp with milliseconds.

Example: 1483228800000

Network & Location 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—do not use both Must supply either `ip` or `use_ip` to avoid data rejection Example: `true`
`country`	ISO 3166-1 alpha-2 two-letter country code. Required When: IP address not available or `use_ip=true` Example: `US`
`ua`	URL-encoded User Agent string. Raw: `Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...` Encoded: `Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...`
`c` iOS, Android	Network connection type. Allowed Values: `wifi`, `carrier` Example: `wifi`
`cn` iOS, Android	Carrier name of internet provider. Example: `Comcast`

Custom Properties

Parameter Description

global_properties

URL-encoded JSON object with custom key-value pairs.

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

Uninstall Tracking Support

Parameter Description

apns_token
iOS

Hex-encoded Apple Push Notification Service (APNs) device token.

Required for iOS uninstall tracking
Must be hex-encoded string
Retrieve APNs Token

Example: b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052

fcm
Android

Firebase Cloud Messaging device token.

Required for Android uninstall tracking
Retrieve FCM Token

Example: bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvD...MExUdFQ3P1

Data Privacy Parameters

Parameter Description

data_sharing_options

JSON URL-encoded end-user consent for data sharing. Must persist and pass on all subsequent SESSION and 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

dnt
iOS, Android

Do Not Track status.

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

Example: 0

dntoff
iOS, Android

Indicates if Do Not Track is OFF.

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

Example: 1

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 session 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 session time.

Example: 1483228800

Google Ads ICM Support (Beta)

Parameter Description

odm_info
iOS

Required for Google Ads Integrated Conversion Measurement (Beta).

Google Ads ICM Documentation

odm_error
iOS

Required for Google Ads Integrated Conversion Measurement (Beta).

Google Ads ICM Documentation

Request Examples

Sample code demonstrates SESSION 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',
    '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 Example

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"

HTTP Example

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

Java Example

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

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

SDK Console Session Event

Critical Verification: Confirm SESSION event occurs on app open/foreground BEFORE any EVENT requests. Invalid order causes attribution errors.

Success Indicator: If SESSION appears in SDK Console, you've completed successful end-to-end integration test!

Additional Resources

Testing Documentation

Comprehensive testing guide: S2S Integration Testing Guide

Server-to-Server - SESSION Endpoint API Reference

SESSION Endpoint API Reference

Overview

Server-to-Server Use Case

Data Flow Architecture

Key Considerations

Session Management

When to Send Sessions

Session Triggers

Session Timeout Logic

Attribution Processing

Session-Based Attribution

Event Order Requirements

Advanced Options

Extended Functionality

API Endpoint Specification

Endpoint URL

Base URL and Method

Required Parameters

API Authentication

SDK Key

Device Identifiers

Platform-Specific Identifiers

Device Parameters

Device Information

Application Parameters

App Information

Fraud Prevention Parameters

Install Source Validation

Deep Linking Parameters

Deep Link Support

Advanced Attribution Parameters

Platform Attribution Enhancement

Optional Parameters

Timestamp Parameters

Network & Location Parameters

Custom Properties

Uninstall Tracking Support

Data Privacy Parameters

Cross-Device Support

SKAdNetwork Support

Google Ads ICM Support (Beta)

Request Examples

Python Example

cURL Example

HTTP Example

Java Example

Response Codes & Errors

Testing & Validation

Testing Procedure

End-to-End Validation

Additional Resources

Testing Documentation