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.

This article covers ad-revenue-specific parameters and workflows. Shared S2S endpoints, authentication, and common parameters are defined once in the S2S Fundamentals hub. For non-ad-revenue in-app events and revenue, see the EVENT Endpoint API Reference .

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.

These are shared S2S parameters defined once in S2S Fundamentals .

V2 Endpoint Identifiers

SDID-Only Requirement

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

Parameter Details


        sdid

UUID

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

These are shared S2S parameters defined once in S2S Fundamentals .

Device Parameters

These are shared S2S parameters defined once in S2S Fundamentals .

Application Parameters

These are shared S2S parameters defined once in S2S Fundamentals .

Event Parameters

Parameter	Details
`n`	`string` 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` 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`	`boolean` Specifies whether event is Ad Monetization revenue event for Ad Revenue Metrics. Pass `true` for this event Example: `true`
`is_revenue_event`	`boolean` Specifies whether event is revenue event for Revenue Metrics. Pass `true` for this event Example: `true`
`amt`	`number` Currency amount of impression revenue. Use in conjunction with `cur` parameter Example: `0.00782`
`cur`	`string` 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

These are shared S2S parameters defined once in S2S Fundamentals .

Data Privacy

These are shared S2S parameters defined once in S2S Fundamentals .

Cross-Device Support

These are shared S2S parameters defined once in S2S Fundamentals .

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