PC & Console API Endpoint Reference

Complete API reference for PC and Console server-to-server endpoints, providing detailed parameter specifications and implementation examples for session tracking and event reporting.

Enterprise Feature: PC and Console game attribution is an enterprise feature. To learn more, read the PC and Console Game Attribution FAQ or contact your Customer Success Manager.

Integration Guide: For complete implementation instructions and best practices, see PC & Console S2S Integration Guide.

Session Notification Endpoint

Report game launches and sessions to Singular for install attribution, re-engagement tracking, and user retention analytics.

Endpoint Specification

Method	URL
`GET`	`https://s2s.singular.net/api/v1/launch`

Purpose

Use Session Notification Endpoint to report all game launches (first and repeat sessions) in near real-time. First game launch received by Singular for install identified by Singular Device ID triggers attribution process.

Attribution Workflow:

First Session: Triggers install attribution matching against web campaign clicks
Subsequent Sessions: Tracked for user activity, retention, and re-engagement analytics
Real-Time Reporting: Send session notifications as close to actual game launch as possible

Session Parameters

Required Parameters

Parameter	Description	Constraints	Example
`a`	Singular SDK Key for API authentication. Location: Dashboard → Developer Tools → SDK Integration → SDK Keys Important: Use SDK Key, not Reporting API Key	Required String	`your_org_name_sh868sdjv`
`p`	Platform where user plays game. Supported Values: `pc` `xbox` `playstation` `nintendo` `metaquest`	Required String Case-sensitive	`pc`
`i`	Game identifier unique for your game. Critical: Must match Web SDK Product ID exactly for attribution to work. Use same value across all platforms for same game.	Required Reverse DNS notation recommended Case-sensitive	`com.singular.game`
`sdid`	Singular Device ID identifying unique game installation and user activity. Generation: Created by game/server at first launch, persists throughout game installation lifetime.	Required UUID Version 4 format recommended	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	Operating System or Game System. Custom values supported, but recommended values by platform: PC: windows, linux, macos, steamos Xbox: xbox_one, xbox_360, xbox_series_s, xbox_series_x PlayStation: playstation_3, playstation_4, playstation_5 Nintendo: nintendo_switch Meta Quest: metaquest, metaquest_2, metaquest_pro	Required Custom values supported	`windows`
`install_source`	Game store or distribution method. Recommended Values: `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` Custom values supported	Required Custom values supported	`steam`
`ip`	IP address of device at time of game launch. Alternative: Use `use_ip=true` to extract IP from HTTP request header instead of passing explicitly.	Required IPv4 or IPv6 format Not required if `use_ip=true`	`172.58.29.235`

Optional Parameters

Parameter	Description	Constraints	Example
`match_id`	Identifier for deterministic attribution matching web clicks to game installs. Requirements: Must be sent on first game launch only Must match value from Web SDK implementation If PII, must be hashed using SHA-256 See Match ID Attribution for implementation details.	Optional String First launch only	`matchid_12345`
`ve`	Operating system version.	Optional String	`22H2`
`av`	Application version or game build identifier.	Optional String	`1.1.5.581823a`
`use_ip`	Extract IP address from HTTP request header instead of requiring explicit `ip` parameter. If set to `true`, do not provide `ip` parameter.	Optional Boolean Default: false	`true`
`ua`	User Agent string of device.	Optional String	`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`
`global_properties`	Key-value pairs saved for user and persisted across all subsequent requests. Not sending previously set value unsets it. Format: URL-encoded JSON object	Optional Up to 5 properties 200 characters max each URL-encoded JSON	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	User consent to share information for privacy compliance. Must be persisted and passed on every subsequent request if set. Values: `"limit_data_sharing":false` - User opted in (consented) `"limit_data_sharing":true` - User opted out (refused) See User Privacy for implementation guidance.	Optional URL-encoded JSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	Install flag indicating first session after game installation. Required for reinstall tracking capabilities.	Optional Boolean	`true`
`utime`	Timestamp of game launch in UNIX time (seconds).	Optional Integer (UNIX timestamp)	`1483228800`
`umilisec`	Timestamp of game launch in UNIX time (milliseconds).	Optional Integer (UNIX timestamp ms)	`1483228800000`
`custom_user_id`	Custom user identifier from your system.	Optional String	`123456789abcd`

Request Examples

Sample Implementations

Basic Session Request

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235"

First Launch with Match ID

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235" \
  --data-urlencode "match_id=abc123def456" \
  --data-urlencode "install=true"

Basic Session Request

import requests

def report_session(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_session({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'ip_address': '172.58.29.235'
})

First Launch with Match ID

def report_first_launch(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address'],
        'match_id': config['match_id'],
        'install': 'true'
    }
    
    response = requests.get(url, params=params)
    return response.json()

Basic Session Request

async function reportSession(config) {
    const url = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportSession({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    ipAddress: '172.58.29.235'
});

First Launch with Match ID

async function reportFirstLaunch(config) {
    const url = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': config.ipAddress,
        'match_id': config.matchId,
        'install': 'true'
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

Event Notification Endpoint

Report in-game events to Singular for analytics, campaign optimization, and partner forwarding.

Endpoint Specification

Method	URL
`GET`	`https://s2s.singular.net/api/v1/evt`

Purpose

Use Event Notification Endpoint to report all desired in-game events in near real-time. Event data used for analytics, reporting, partner optimization, and campaign performance measurement.

Event Best Practices:

Standard Events: Use Singular standard event names for automatic partner mapping
Real-Time Reporting: Send events as close to actual occurrence as possible
Revenue Events: Include revenue parameters for purchase tracking and ROI analysis

Event Parameters

Required Parameters

Parameter	Description	Constraints	Example
`a`	Singular SDK Key for API authentication. Location: Dashboard → Developer Tools → SDK Integration → SDK Keys	Required String	`your_org_name_sh868sdjv`
`p`	Platform where user plays game. Supported Values: pc, xbox, playstation, nintendo, metaquest	Required String Case-sensitive	`pc`
`i`	Game identifier unique for your game. Must match value used in session notifications and Web SDK Product ID.	Required Reverse DNS notation recommended Case-sensitive	`com.singular.game`
`sdid`	Singular Device ID identifying unique game installation. Must match SDID used in session notifications.	Required UUID format	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	Event name identifying in-game action or milestone. Recommended: Use Singular standard event names for automatic partner integration.	Required String 32 ASCII characters max	`sng_achievement_unlocked`
`os`	Operating System or Game System. Must match value used in session notifications.	Required Custom values supported	`windows`
`install_source`	Game store or distribution method. Must match value used in session notifications.	Required Custom values supported	`steam`
`ip`	IP address of device at time of event.	Required IPv4 or IPv6 format Not required if `use_ip=true`	`172.58.29.235`

Optional Parameters

Parameter	Description	Constraints	Example
`e`	Custom event attributes providing rich information about event. Recommended: Use Singular standard attribute names for partner compatibility.	Optional URL-encoded JSON 500 ASCII characters max per attribute	`%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	Marks event as revenue event. Can be omitted if event name is `__iap__` or non-zero `amt` provided.	Required for revenue events Boolean	`true`
`amt`	Currency amount for revenue event. Use with `cur` parameter.	Required for revenue events Decimal number	`2.51`
`cur`	ISO-4217 three-letter currency code for revenue event. Use with `amt` parameter. Reference: ISO-4217 Currency Codes	Required for revenue events ISO-4217 code	`EUR`
`ve`	Operating system version.	Optional String	`22H2`
`av`	Application version or game build identifier.	Optional String	`1.1.5.581823a`
`use_ip`	Extract IP address from HTTP request header.	Optional Boolean Default: false	`true`
`ua`	User Agent string of device.	Optional String	`Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
`global_properties`	Key-value pairs saved for user. Must persist across all subsequent requests if set.	Optional Up to 5 properties 200 characters max each URL-encoded JSON	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	User consent to share information. Must persist across all subsequent requests if set.	Optional URL-encoded JSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`utime`	Timestamp of event in UNIX time (seconds).	Optional Integer (UNIX timestamp)	`1483228800`
`umilisec`	Timestamp of event in UNIX time (milliseconds).	Optional Integer (UNIX timestamp ms)	`1483228800000`
`custom_user_id`	Custom user identifier from your system.	Optional String	`123456789abcd`

Request Examples

Sample Implementations

Standard Event

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=sng_level_achieved" \
  --data-urlencode 'e={"sng_attr_level":"5","sng_attr_score":"1250"}' \
  --data-urlencode "ip=172.58.29.235"

Revenue Event

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=__iap__" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=9.99" \
  --data-urlencode "cur=USD" \
  --data-urlencode "ip=172.58.29.235"

Standard Event

import requests
import json

def report_event(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': config['event_name'],
        'ip': config['ip_address']
    }
    
    if 'attributes' in config:
        params['e'] = json.dumps(config['attributes'])
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_event({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'event_name': 'sng_level_achieved',
    'attributes': {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    'ip_address': '172.58.29.235'
})

Revenue Event

def report_revenue(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config['amount'],
        'cur': config['currency'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_revenue({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'amount': 9.99,
    'currency': 'USD',
    'ip_address': '172.58.29.235'
})

Standard Event

async function reportEvent(config) {
    const url = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'n': config.eventName,
        'ip': config.ipAddress
    });
    
    if (config.attributes) {
        params.append('e', JSON.stringify(config.attributes));
    }
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportEvent({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    eventName: 'sng_level_achieved',
    attributes: {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    ipAddress: '172.58.29.235'
});

Revenue Event

async function reportRevenue(config) {
    const url = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config.amount,
        'cur': config.currency,
        'ip': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportRevenue({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    amount: 9.99,
    currency: 'USD',
    ipAddress: '172.58.29.235'
});

Response Handling

Both endpoints return consistent JSON responses requiring validation of status field for success or error determination.

Response Format

Important: All responses return HTTP 200 status codes. Always validate response body's status field to determine success (ok) or failure (error).

For complete response code documentation and error handling strategies, see S2S Response Codes & Error Handling.

Additional Resources

Integration Guide:PC & Console S2S Integration Guide
Web SDK:Web SDK Overview & Getting Started
Attribution FAQ:PC and Console Game Attribution FAQ
Standard Events:Singular Standard Events Reference

PC & Console - API Endpoint Reference

PC & Console API Endpoint Reference

Session Notification Endpoint

Endpoint Specification

Purpose

Session Parameters

Required Parameters

Optional Parameters

Request Examples

Sample Implementations

Basic Session Request

First Launch with Match ID

Basic Session Request

First Launch with Match ID

Basic Session Request

First Launch with Match ID

Event Notification Endpoint

Endpoint Specification

Purpose

Event Parameters

Required Parameters

Optional Parameters

Request Examples

Sample Implementations

Standard Event

Revenue Event

Standard Event

Revenue Event

Standard Event

Revenue Event

Response Handling

Response Format

Additional Resources