Tracking Ad Revenue API Reference

Server-to-Server Use Case

Singular enables tracking ad revenue via the EVENT API. By forwarding impression-level revenue details from your mediation platform(s) to your server using paid event handlers, Singular processes this data for seamless integration into reports, export logs, and postbacks. The platform also supports automatic currency conversion aligned with your organization’s preferred settings.

The Singular REST API enables direct server-to-server integration as an alternative to the SDK. While the SDK automatically collects device and app data, the S2S approach requires you to:

Collect required EVENT API data points from your app
Collect relevant mediation platform data points
Forward this data to your server
Send the '__ADMON_USER_LEVEL_REVENUE__' Event to Singular via REST API

Key Points

Flexibility: Full control over data collection and transmission
Feature Parity: Supports all SDK functionality when proper data is provided
Integration Path: Client → Your Server → Singular API
Real-time processing: One request at a time, no batch processing
Sequential data flow: Events must be processed in chronological order
Data Deduplication: Singular does not deduplicate received data. It is recommended to send one(1) successful Request and save logs in the event a Request should be replayed.
Data Validation: Device-level data is permanent and cannot be deleted once ingested. Implement thorough data validation before sending data to Singular to ensure accuracy.

Prerequisites

A Session must be established before any event tracking is received
Invalid session order will result in data inconsistencies
Collect Mediation Platform data attributes directly from the Mediation SDK. For implementation details and required data points, refer to our SDK Guide and platform-specific Mediation documentation.

Getting Started

The EVENT endpoint documentation provides:

Required parameters
Optional parameters
Request Examples
Response Codes & Errors
Event Testing

This server-side approach gives you more control over your integration while maintaining all SDK capabilities.

Event API Endpoint

HTTP Method and Event Endpoint

GET https://s2s.singular.net/api/v1/evt

Required Parameters

The table below lists the required parameters for sending Ad Monetization Revenue events via the Event API. These parameters should be included as query parameters.

GET /api/v1/evt?param1=value1&param2=value2

All required parameters must be included in EVENT API requests
Parameters should follow specified format and data types

Required Parameters
API Key
Parameter	Description
`a`	`string` The a parameter specifies the Singular SDK Key. Retrieve the SDK Key from the Singular UI, under Developer Tools in the Main Menu. Note: Do not use the reporting API Key as this will result in rejected data. Example Value: `sdkKey_afdadsf7asf56`
Device Identifier Parameters
Parameter	Description
`idfa` Supported Platforms: iOS	`string` The idfa parameter specifies the Identifier for Advertisers (IDFA) which helps advertisers track and attribute user actions (e.g., ad clicks, app installs) to specific campaigns, enabling precise ad targeting and campaign optimization. Starting with iOS 14.5, users must opt-in via the App Tracking Transparency (ATT) framework before apps can access the IDFA. If users do not opt-in to IDFA then the IDFA will be unavailable resulting in limiting tracking capabilities. If the IDFA is unavailable then omit the parameter from the request. Do not pass NULL or empty string in the request. How to retrieve the IDFA Identifier Example Value: `DFC5A647-9043-4699-B2A5-76F03A97064B`
Parameter	Description
`idfv` Supported Platforms: iOS	`string` The idfv parameter specifies the Identifier for Vendors (IDFV), a unique identifier assigned by Apple to a device, which is specific to a particular vendor or developer. It remains consistent across all apps from the same vendor on a given device, allowing the vendor to track user behavior and interactions across their app ecosystem without identifying the user personally. The IDFV is required on all request regardless of ATT status or the presence of the IDFA. How to retrieve the IDFV Identifier Example Value: `21DB6612-09B3-4ECC-84AC-B353B0AF1334`
Parameter	Description
`aifa` Supported Platforms: Android (Google Play Devices)	`string` The aifa parameter specifies the Google Advertising Identifier (GAID), also known as AIFA in Singular or Android Advertising ID (AAID). This identifier is a unique, user-resettable identifier assigned to Android devices. It helps advertisers and app developers track and attribute user actions (e.g., ad clicks, app installs) across apps to specific campaigns, enabling precise ad targeting and campaign optimization, while maintaining user privacy. If the AIFA is unavailable then omit the parameter from the request. Only required on Google Play Devices. Omit the parameter on Non-Google Play devices. Do not pass NULL or empty string in the request. How to retrieve the AIFA Identifier Example Value: `8ecd7512-2864-440c-93f3-a3cabe62525b`
Parameter	Description
`asid` Supported Platforms: Android (Google Play Devices)	`string` The asid parameter specifies the Android App Set ID. The ASID provides a way for developers to track users across their own apps in a privacy-conscious manner. It is particularly useful for analytics and fraud prevention but cannot be used for advertising purposes such as personalized ads or measurement. The ASID is required on all request for Google Play Devices, regardless of GAID/AIFA presence. Omit the parameter on Non-Google Play devices. Do not pass NULL or empty string in the request. How to retrieve the ASID Identifier Example Value: `edee92a2-7b2f-45f4-a509-840f170fc6d9`
Parameter	Description
`amid` Supported Platforms: Android (Amazon Devices without Google Play Services)	`string` The amid parameter specifies the Advertising ID is a user-resettable, unique identifier that helps protect the privacy of the user. If you collect information about a user’s behavior to display interest-based ads, or to generate analytics, you must use the Advertising ID; no other identifier or tracking method may be used. Users can reset the Advertising ID or opt out of interest-based ads altogether. The AMID is required on all request for Amazon Devices without Google Play Services. Omit the parameter if AMID is unavailable. Do not pass NULL or empty string in the request. How to retrieve the AMID Identifier Example Value: `df07c7dc-cea7-4a89-b328-810ff5acb15d`
Parameter	Description
`oaid` Supported Platforms: Android (Chinese-manufactured Devices without Google Play Services)	`string` The oaid parameter specifies Open Advertising Identifier (OAID). The OAID is a unique, anonymous identifier used for advertising purposes on Android devices, particularly those manufactured in China. It was introduced by the Mobile Security Alliance (MSA) as an alternative to Google's Advertising ID (GAID) for devices where Google Play Services are unavailable or not supported, such as in the Chinese market. The OAID is primarily used for advertising attribution and user tracking in environments where Google Play Services are restricted, allowing advertisers and developers to track user behavior while maintaining anonymity. OAID is available on most Chinese-manufactured Android devices, including those from brands like Huawei, Xiaomi, and others. It can be accessed using the MSA SDK or Huawei Mobile Services (HMS). The OAID is required on Chinese-manufactured Android devices without Google Play Services. Omit the parameter if OAID is unavailable. Do not pass NULL or empty string in the request. How to retrieve the OAID Identifier Example Value: `01234567-89abc-defe-dcba-987654321012`
Parameter	Description
`andi` Supported Platforms: Android (Non Google Play devices)	`string` The andi parameter specifies the Android ID which is a unique 64-bit identifier generated by the Android operating system when a device is first set up. It is designed to be persistent across the lifetime of the device, but it can be reset under certain conditions such as a factory reset. The Android ID is unique to each device and, starting from Android 8.0 (Oreo), it is scoped per app and per user. This means that different apps on the same device will receive different Android IDs unless they share the same signing key. The Android ID remains constant unless the device undergoes a factory reset or if an app is uninstalled and reinstalled after an OTA (over-the-air) update. The ANDI is prohibited for use on Google Play Devices. Use the AIFA and ASID identifiers mentioned above. The ANDI may be sent to Singular only if no other identifiers are available, and the App is not hosted on Google Play Store. Omit the parameter if other identifiers are available. Do not pass NULL or empty string in the request. How to retrieve the ANDI Identifier Example Value: `fc8d449516de0dfb`
Device Parameters
Parameter	Description
`p`	`string` The p parameter specifies the platform of the App. The following list contains the allowed case-sensitive parameter values: Android iOS Example Value: `Android`
Parameter	Description
`ip`	`string` The ip parameter specifies the public (IPV4) IP Address of the device. IPV6 is not supported. Example Value: `172.58.29.235`
Parameter	Description
`ve`	`string` The ve parameter specifies the OS Version of the device at event time. Example Value: `9.2`
Application Parameters
Parameter	Description
`i`	`string` The i parameter specifies the App Identifier. This is a case-sensitive value: Package Name for Android Bundle ID for iOS Example Value: `com.singular.app`
Parameter	Description
`att_authorization_status` Supported Platforms: iOS	`int` The att_authorization_status parameter specifies the App Tracking Transparency(ATT) status code. Starting with iOS 14.5, the App Tracking Transparency (ATT) prompt is required in order to access the IDFA identifier. Note: Even if you don't implement the ATT prompt, we require that you pass the ATT authorization status with the value '0', indicating "undetermined". Supported values are: 0 - Undetermined. 1 - Restricted, the user disabled app tracking. 2 - Denied, the user denied authorization. 3 - Authorized, the user granted authorization. Examples: `3`
Event Parameters
Parameter	Description
`n`	`string` The n parameter specifies the Name of the event being tracked. Supporting AdMon Revenue requires the Event Name to be a specific value. Event Name must be ALL UPPERCASE with underscores. Use the following Event Name: `__ADMON_USER_LEVEL_REVENUE__`
Parameter	Description
`e`	`JSON URL-encoded string` The e parameter specifies custom event attributes in JSON format. The only required attribute is the 'ad_platform'. All other attributes are optional. The possible attributes are: ad_platform -- REQUIRED 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 Note: Attributes without values should be omited. `{ "ad_platform":"AdMob", "ad_mediation_platform":"admob.AdMobAdapter", "ad_unit_id":"ca-app-pub-6325336052\/44923540" }` Example Value: `%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`
Parameter	Description
`is_admon_revenue`	`string` The is_admon_revenue parameter specifies whether the event is an Ad Monetization revenue event and should be used for Ad Revenue Metrics. Pass 'true' for this event. Example Value: `true`
Parameter	Description
`is_revenue_event`	`string` The is_revenue_event parameter specifies whether the event is a revenue event and should be used for Revenue Metrics. Pass 'true' for this event. Example Value: `true`
Parameter	Description
`amt`	`double` The amt parameter specifies the currency amount. This should be used in conjunction with the 'cur' parameter. Example Value: `0.00782`
Parameter	Description
`cur`	`string` The cur parameter specifies the uppercase ISO 4217 three-letter currency code. This should be used in conjunction with the 'amt' parameter. Example Value: `USD`

Request Body

Do not provide a request body when calling this method. The request must be sent using the GET method with query parameters.

Request Examples

The following code samples may not represent all supported parameters. When implementing the request be sure to include all required parameters as listed above, and validate that the correct values are being passed before sending data from a production instance. It is advised to uses a unique application identifier for development and testing.

PYTHON

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

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

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 application-level status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

Optional Parameters

The following table lists the optional parameters that this endpoint supports. All of the parameters listed are query parameters.

Optional Parameters
Device & Network Parameters
Parameter	Description
`use_ip`	`string` The use_ip parameter tells Singular to extract the IP Address from the HTTP request instead of the 'ip' parameter. Pass 'true' to use this feature. Using this parameter prevents Singular from geo-locating the device based on IP Address. You may supply the two-letter country code of the user in the optional 'country' parameter. This parameter is mutually exclusive to the 'ip' parameter. DO NOT use this with the 'ip' parameter. To avoid data rejection, you must supply either 'ip' or the 'use_ip' parameter on the request. Example Value: `true`
Parameter	Description
`country`	`string` The country parameter should contain the ISO 3166-1 alpha-2 two-letter country code of the user at the time of the event execution. This parameter is required only when: The 'ip' parameter is not available If the 'ip' parameter is available, the country will be automatically determined from the IP address, and the 'country' parameter is not needed. Example Value: `US`
Data Privacy
Parameter	Description
`data_sharing_options`	`JSON URL-encoded string` The data_sharing_options parameter specifies the end-user's consent to share information. If set, this value must be persisted and passed on every subsequent 'SESSION' and 'EVENT' request for the user. To indicate that the user consented (opted-in) to share their information pass 'false': `{"limit_data_sharing":false}` If the user refused then pass 'true': `{"limit_data_sharing":true}` The value must be a URL-encoded JSON String. Example Value: `%7B%22limit_data_sharing%22%3Atrue%7D`
Cross Device Support
Parameter	Description
`custom_user_id`	`string` The custom_user_id parameter specifies your internal User ID. Example Value: `123456789abcd`

Event Testing

After integrating the server-to-server integration, it is essential to verify that Singular receives data before you go live with a production instance. Refer to our testing guide for more details. At a high level the following steps should be followed:

Obtain your test device Advertising ID and add the ID in the Singular SDK Console.
Open the Singular SDK Console and add the device identifier to start capturing data.
Override the App Identifier with a development App Identifier (com.singular.app.dev) to keep test data and events separate from production data.
Build or Open the App from a terminated state
Validate the App Open is sent to your server with all required Singular data points
Validate your server triggers the Session Notification to the Singular 'launch' endpoint with all required data points.
After a few seconds, the Session event should be displayed in the Singular SDK Console.
Proceed to triggering an Event in the App.
Validate that the Event is sent to your server with all required Singular data points
Validate your server triggers the Event Notification to the Singular 'evt' endpoint with all required data points.
After a few seconds, the Event should be displayed in the Singular SDK Console.
Repeat the test, to validate all events are sent as expected and with the expected values.

Important Verifications

Confirm that the Session Event occurs on App Open or to Foreground and before the Event is received.
Confirm that the Event required data points, match the Session data points.
Confirm the correct Mediation Platform details are passed in the Event Arguments
Confirm the correct Revenue Amount and Currency

If you see your Events in the SDK Console, you have completed an end-to-end test of Event handling!