Server-to-server events
Send events directly from your server to Adtrace using the S2S Event API. S2S events appear the same as SDK events in the panel.
The SDK handles queuing, retries, and client-side delivery, so send routine in-app events through the SDK when possible. Use S2S for sensitive or server-validated events — not for every event in your app.
Before any S2S event is accepted, the device must have a recorded install. Integrate the Adtrace SDK on Android, iOS, or Web first, then send selected events from your server.
Verify the device has an install in the Testing Console in the panel before you send S2S events.
Sending past or aggregated revenue
You can send S2S events at any time after an install exists for a device.
| Topic | Behavior |
|---|---|
| Install | Must already exist for that device. |
| Event time | By default, the timestamp is when Adtrace receives the request. |
sent_at | Optional ISO 8601 value if you need a specific event time. |
| Historical backfill | You can send aggregated past revenue in one call, but it does not recreate individual past event rows unless you send separate requests with appropriate sent_at values. |
Endpoint
| URL | https://s2s.adtrace.io/s2s/event |
| Method | POST |
| Content-Type | application/json |
| Authorization | Token <S2S API KEY> |
Get your S2S API key from the Adtrace panel (Dashboard → Settings).
Common request body fields
| Field | Required | Description |
|---|---|---|
app_token | Yes | Your app token from the panel. Example: abc123xyz456 |
event_token | Yes | Your event token from the panel. Example: xyz123 |
os_name | Yes* | "android" or "ios" for mobile. See Web for web identifiers. |
revenue | No | Revenue amount as a string. Example: "5000000" |
currency | No | Currency label. Required when revenue is set. Example: "IRR" |
sent_at | No | Event timestamp in ISO 8601. Example: 2024-01-01T01:01:01.001Z+0000 |
event_value_params | No | Event parameters as a JSON string. Example: "{\"key1\":\"value1\"}" |
* Web events may use web_uuid without os_name — see the Web section below.
Every request must include one platform device identifier. Do not omit all identifiers.
Android
Set os_name to "android" (lowercase).
| Field | Required | Description |
|---|---|---|
gps_adid | One required* | Google Play Services advertising ID. |
adtrace_adid | One required* | Adtrace device ID (adid). Use when gps_adid is unavailable. |
Read identifiers from the Android SDK or the Testing Console.
Example (Android)
curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
--header 'Authorization: Token YOUR_S2S_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_token": "YOUR_APP_TOKEN",
"os_name": "android",
"gps_adid": "DEVICE_GPS_ADID",
"event_token": "YOUR_EVENT_TOKEN",
"revenue": "5000000",
"currency": "IRR"
}'
Example with adtrace_adid (Android)
curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
--header 'Authorization: Token YOUR_S2S_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_token": "YOUR_APP_TOKEN",
"os_name": "android",
"adtrace_adid": "DEVICE_ADTRACE_ADID",
"event_token": "YOUR_EVENT_TOKEN"
}'
iOS
Set os_name to "ios" (lowercase).
| Field | Required | Description |
|---|---|---|
idfa | One required* | Apple Identifier for Advertisers. Available only when the user authorizes tracking. |
adtrace_adid | One required* | Adtrace device ID (adid). Use when idfa is unavailable. |
Read identifiers from the iOS SDK or the Testing Console.
Example (iOS)
curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
--header 'Authorization: Token YOUR_S2S_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_token": "YOUR_APP_TOKEN",
"os_name": "ios",
"idfa": "DEVICE_IDFA",
"event_token": "YOUR_EVENT_TOKEN",
"revenue": "9.99",
"currency": "USD"
}'
Example with adtrace_adid (iOS)
curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
--header 'Authorization: Token YOUR_S2S_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_token": "YOUR_APP_TOKEN",
"os_name": "ios",
"adtrace_adid": "DEVICE_ADTRACE_ADID",
"event_token": "YOUR_EVENT_TOKEN"
}'
Web
For web integrations, send web_uuid or adid as the device identifier. Retrieve web_uuid with Adtrace.getWebUUID() and pass it to your backend.
| Field | Required | Description |
|---|---|---|
web_uuid | One required* | Web device identifier from the Web SDK. |
adid | One required* | Adtrace device ID from attribution. Use when web_uuid is unavailable. |
Example (Web)
curl --location --request POST 'https://s2s.adtrace.io/s2s/event' \
--header 'Authorization: Token YOUR_S2S_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_token": "YOUR_APP_TOKEN",
"web_uuid": "DEVICE_WEB_UUID",
"event_token": "YOUR_EVENT_TOKEN"
}'
See Web FAQ — S2S events for web-specific guidance.
Troubleshooting
| Status | Error | What to do |
|---|---|---|
| 404 | Install for device not found | No install record exists. Open the app or site so the SDK sends an install, then verify in the Testing Console. |
| 404 | Device ids not found | Include a platform device identifier (gps_adid, idfa, web_uuid, or adtrace_adid). |
| 403 | IP address is not valid | Add your server IP to the IP allowlist in the panel. Run curl ident.me on the server to confirm the outbound IP. |
| 400 | Os name must be android or ios | Set os_name to "android" or "ios" exactly (lowercase) for mobile requests. |