Ad Revenue Tracking API Reference

Track impression-level ad monetization 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

Ad Revenue API enables impression-level ad monetization tracking where apps forward revenue data from mediation platforms to your backend, which transmits to Singular's servers for ad revenue analytics and reporting.

Supported Capabilities:

Ad Monetization Revenue: Track impression-level revenue from mediation platforms
Platform Attribution: Connect ad revenue to user acquisition campaigns
Mediation Integration: Support for all major ad mediation platforms
Currency Conversion: Automatic currency conversion aligned with organization settings

Data Flow Architecture

Server-to-server ad revenue tracking follows a four-step data transmission process.

Client Collection: App collects impression-level revenue data from mediation platform SDK
Server Transmission: App forwards ad revenue data to your backend server
Device Graph Query: Server retrieves or updates device details from Singular device graph
Event API Call: Server sends __ADMON_USER_LEVEL_REVENUE__ event to Singular REST API endpoint

Critical Requirements

Prerequisites:

Session Before Events: SESSION must be established before any ad revenue tracking
Sequential Order: Invalid session order results in data inconsistencies and attribution errors
Mediation Platform Data: Collect required attributes directly from Mediation SDK—refer to SDK Guide for implementation details

Integration Constraints:

Real-time Processing: Requests processed individually—no batch support
Chronological Events: Events must be sent in order they occurred
No Deduplication: Singular does not deduplicate data—implement server-side deduplication to prevent duplicates
Data Permanence: Device-level data cannot be deleted after ingestion—validate before sending

API Endpoint Selection

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

Endpoint Selection: Choose endpoint based on your integration architecture and device identifier strategy. Use-case determines correct endpoint.

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

Account Enablement: V2 endpoint requires Singular account configuration for SDID usage. Contact your Solution Engineer or CSM for enablement.

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.

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 Omit parameter if IDFA unavailable (user denied ATT) 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. Required on Google Play devices Omit on non-Google Play devices 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 Retrieve ASID Example: `edee92a2-7b2f-45f4-a509-840f170fc6d9`
`amid`	Android (Amazon)	Amazon Advertising ID for Amazon Fire devices without Google Play Services. Required for Amazon devices Retrieve AMID Example: `df07c7dc-cea7-4a89-b328-810ff5acb15d`
`oaid`	Android (Chinese OEMs)	Open Advertising Identifier (OAID) for Chinese-manufactured devices without Google Play Services. Required for Huawei, Xiaomi, OPPO, Vivo devices without Google Play 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. Only use if no other identifiers available and app not distributed via Google Play. Retrieve ANDI Example: `fc8d449516de0dfb`

V2 Endpoint Identifiers

SDID-Only Requirement

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

Parameter Description

sdid

Platforms: iOS, Android

Singular Device ID obtained from Singular SDK or generated client-side.

iOS/Android: Requires account enablement for SDID usage—SDK callback method provides SDID after initialization
Identifier Simplification: Eliminates need for AIFA, ASID, IDFA, IDFV parameters
Retrieve SDID

Example: 40009df0-d618-4d81-9da1-cbb3337b8dec

Required Parameters

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

Parameter Format: All parameters must be passed as URL query parameters using GET method. Do not send parameters in JSON request body.

API Authentication

Parameter Type Description

a

string

Singular SDK Key for API authentication.

Retrieve From: Singular UI → Main Menu → Developer Tools

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

Example: sdkKey_afdadsf7asf56

Device Parameters

Parameter Description

p

Platform of the application (case-sensitive).

Allowed Values: Android, iOS

Example: Android

ip

Public IPv4 IP address of device. IPv6 supported but IPv4 recommended for attribution compatibility.

Example: 172.58.29.235

ve

OS version of device at event time.

Example: 9.2

Application Parameters

Parameter Description

i

App identifier (case-sensitive).

Android: Package Name (e.g., com.singular.app)
iOS: Bundle ID (e.g., com.singular.app)

Example: com.singular.app

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

Event Parameters

Parameter	Description
`n`	Name of the event being tracked. Required Event Name for Ad Revenue: `__ADMON_USER_LEVEL_REVENUE__` Event name must be ALL UPPERCASE with underscores Maximum 32 ASCII characters
`e`	JSON URL-encoded string specifying custom event attributes from mediation platform. Required Attributes: `ad_platform` - (REQUIRED) Name of ad network Optional Attributes: `ad_mediation_platform` `ad_type` `ad_group_type` `ad_impression_id` `ad_placement_name` `ad_unit_id` `ad_unit_name` `ad_group_id` `ad_group_name` `ad_group_priority` `ad_placement_id` JSON Structure: `{ "ad_platform": "AdMob", "ad_mediation_platform": "admob.AdMobAdapter", "ad_unit_id": "ca-app-pub-6325336052/44923540" }` URL-Encoded Example: `%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%5C%2F44923540%22%7D` Note: Omit attributes without values.
`is_admon_revenue`	Specifies whether event is Ad Monetization revenue event for Ad Revenue Metrics. Pass `true` for this event Example: `true`
`is_revenue_event`	Specifies whether event is revenue event for Revenue Metrics. Pass `true` for this event Example: `true`
`amt`	Currency amount of impression revenue. Use in conjunction with `cur` parameter Example: `0.00782`
`cur`	ISO 4217 three-letter uppercase currency code. Use in conjunction with `amt` parameter Example: `USD`

Optional Parameters

Optional parameters enhance ad revenue tracking with additional context and functionality.

Network 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
Must supply either ip or use_ip

Example: true

country

ISO 3166-1 alpha-2 two-letter country code.

Required When: IP address not available or use_ip=true

Example: US

Data Privacy

Parameter Description

data_sharing_options

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

Cross-Device Support

Parameter Description

custom_user_id

Your internal user ID for cross-device tracking.

Example: 123456789abcd

Request Examples

Sample code demonstrates Ad Revenue EVENT 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',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': '__ADMON_USER_LEVEL_REVENUE__',
    'e': '{"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}',
    'is_admon_revenue': 'true',
    'is_revenue_event': 'true',
    'amt': 0.00782,
    'cur': 'USD'
}

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

cURL Example

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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=__ADMON_USER_LEVEL_REVENUE__" \
  --data-urlencode 'e={"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}' \
  --data-urlencode "is_admon_revenue=true" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=0.00782" \
  --data-urlencode "cur=USD"

HTTP Example

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=__ADMON_USER_LEVEL_REVENUE__
    &e=%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%2F44923540%22%7D
    &is_admon_revenue=true
    &is_revenue_event=true
    &amt=0.00782
    &cur=USD HTTP/1.1
Host: s2s.singular.net
Accept: application/json

Java Example

// 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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "__ADMON_USER_LEVEL_REVENUE__");
params.put("e", "{\"ad_platform\":\"AdMob\",\"ad_mediation_platform\":\"admob.AdMobAdapter\",\"ad_unit_id\":\"ca-app-pub-6325336052/44923540\"}");
params.put("is_admon_revenue", "true");
params.put("is_revenue_event", "true");
params.put("amt", "0.00782");
params.put("cur", "USD");

// 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 ad revenue 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
Build and Launch: Build or open app from terminated state
Validate Client Data: Confirm app sends all required Singular data points to your server
Verify Session: Confirm your server sends SESSION request to https://s2s.singular.net/api/v1/launch with all required parameters
Check SDK Console (Session): Within seconds, SESSION event should appear in SDK Console

SDK Console Session Event

Ad Revenue Event Testing

Trigger Ad Impression: Generate ad impression in app to fire mediation platform callback
Validate Mediation Data: Confirm impression data sent to your server with all required mediation platform attributes
Verify Server Request: Confirm your server sends EVENT request to https://s2s.singular.net/api/v1/evt with all required parameters
Check SDK Console (Event): Within seconds, __ADMON_USER_LEVEL_REVENUE__ event should appear in SDK Console
Repeat Tests: Validate all ad impressions sent with expected values and correct revenue amounts

SDK Console Ad Revenue Event

Critical Verifications:

Confirm SESSION event occurs on app open/foreground BEFORE EVENT received
Confirm EVENT required data points match SESSION data points
Confirm correct Mediation Platform details passed in Event Arguments
Confirm correct Revenue Amount and Currency

Success Indicator: If ad revenue events appear in SDK Console, you've completed successful end-to-end ad revenue integration test!

Additional Resources

Testing Documentation

Comprehensive testing guide: S2S Integration Testing Guide

Server-to-Server - Tracking Ad Revenue API Reference

Ad Revenue Tracking API Reference

Overview

Server-to-Server Use Case

Data Flow Architecture

Critical Requirements

API Endpoint Selection

Event Endpoint V1

V1 Use Cases

Event Endpoint V2

V2 Use Cases

Required Device Identifiers

V1 Endpoint Identifiers

Platform-Specific Identifiers

V2 Endpoint Identifiers

SDID-Only Requirement

Required Parameters

API Authentication

Device Parameters

Application Parameters

Event Parameters

Optional Parameters

Network Parameters

Data Privacy

Cross-Device Support

Request Examples

Python Example

cURL Example

HTTP Example

Java Example

Response Codes & Errors

Testing & Validation

Testing Procedure

End-to-End Validation

Ad Revenue Event Testing

Additional Resources

Testing Documentation