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

The SESSION endpoint notifies Singular when a user opens your app, powering install and re-engagement attribution and retention metrics. New to Server-to-Server? See the S2S Fundamentals guide for core concepts and shared setup.

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

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

API Endpoint Specification

SESSION endpoint accepts POST requests with parameters sent as application/x-www-form-urlencoded .

Endpoint

Base URL and Method

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

Required header:

Content-Type: application/x-www-form-urlencoded

Request Format:

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

param1=value1&param2=value2

Required Parameters

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

API Authentication

SDK Key

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 Identifiers

Platform-Specific Identifiers

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`
`sdid`	Platform: iOS, Android, PC, Xbox, PlayStation, Nintendo, MetaQuest, CTV Type: UUIDv4 Singular Device ID is a client-generated anonymized UUIDv4 representing a unique app install. Primary identifier: Only device identifier relevant for PC and console applications. Example: `40009df0-d618-4d81-9da1-cbb3337b8dec`

Device Parameters

Device Information

Parameter	Details
`p`	Type: String Platform of the application. Allowed values (case-sensitive): Example: `Android` Android iOS 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

App Information

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

Parameter Details

install

Type: Boolean
Indicates if session represents first session after install or reinstall.
Required for: Reinstall tracking capabilities
Example: true

true - First session after fresh install/reinstall
false - Subsequent session (app already installed)

install_time

Platform: iOS, Android
Type: Integer
Unix timestamp (seconds) of when the app was physically installed on the device, as reported by the OS.
Example: 1510040127

This is the device install time, not Singular's attribution install time. Attribution uses the session timestamp ( utime ) of the first session ( install=true ).

See the Device Data Retrieval Guide for how to obtain this value on iOS and Android.

update_time

Platform: iOS, Android
Type: Integer
Unix timestamp (seconds) of when the app was last updated on the device, as reported by the OS.
Example: 1510040127

See the Device Data Retrieval Guide for how to obtain this value on iOS and Android.

Fraud Prevention Parameters

Install Source Validation

Parameter Details

install_source

Platform: Android, PC
Type: String
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

Platform: iOS
Type: String
Base64-encoded iOS install receipt for fraud validation.
Example (truncated): MIJF9wYJKoZIhvcNAQcCoIJF6DCCReQCAQExCzAJBgUrDgMCGgUAMII1m...

Deep Linking Parameters

Deep Link Support

Parameter Details

openuri

Platform: iOS, Android
Type: String
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

Platform: iOS, Android
Type: Boolean
Indicates if app expects deferred deep link URL in response.
Example Response:

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

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

singular_link_resolve_required

Platform: iOS, Android
Type: Boolean
Requests resolution of Singular short link to long link. Must be used with openuri containing Singular short link.
Example Response:

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

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

install_ref Native PC (Google Play Games)

Platform: Android (Google Play)
Type: JSON
JSON URL-encoded Google Install Referrer information. Provides most accurate attribution for Android and Google Play Games PC installs.
Android JSON Structure:
Native PC JSON Structure:
Required For:
More info:

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

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

Facebook user-level exports
Data Destination sharing
Postback accuracy

meta_ref

Platform: Android (Google Play)
Type: JSON

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:
Learn more: Meta Referrer FAQ

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

attribution_token

Platform: iOS
Type: String
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	Details
`utime`	Type: Integer 10-digit Unix timestamp of session. Example: `1483228800`
`umilisec`	Type: Integer 13-digit Unix timestamp with milliseconds. Example: `1483228800000`

Network & Location 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.

Custom Properties

Parameter Details

global_properties

Type: JSON
URL-encoded JSON object with custom key-value pairs.
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

Uninstall Tracking Support

Parameter Details

apns_token

Platform: iOS
Type: String
Hex-encoded Apple Push Notification Service (APNs) device token.
Example: b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052

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

fcm

Platform: Android
Type: String
Firebase Cloud Messaging device token.
Example: bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvD...MExUdFQ3P1

Required for Android uninstall tracking
Retrieve FCM Token

Data Privacy Parameters

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 session 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 session time. Example: `1483228800`

Google Ads ICM Support (Beta)

Parameter	Details
`odm_info`	Platform: iOS Type: String Required for Google Ads Integrated Conversion Measurement (Beta). Google Ads ICM Documentation
`odm_error`	Platform: iOS Type: String 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

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

cURL Example

curl -X POST "https://s2s.singular.net/api/v1/launch" \
  -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 "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

POST /api/v1/launch 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&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

Java Example

// Endpoint
String endpoint = "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 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

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

Session Management

When to Send Sessions

Session Triggers

Session Timeout Logic

Attribution Processing

Session-Based Attribution

Event Order Requirements

API Endpoint Specification

Endpoint

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