Partner Event API

1. Receive the complete handoff package

The destination engineer does not need dashboard access. Ask the customer account Admin for one account-level complete handoff package and verify every item below:

• Key ID + Secret
• Production, validation, catalog, OpenAPI, Developer Hub, and Playground URLs
• Actual App / Campaign name, host, traffic source, and destination URL query key
• Fixed system test App + mrt_ + expiry
• Signing, body-size, rate-limit, retry, and error contracts

Account testing never selects a customer App / Campaign and does not include a production query key. The buyer supplies the real Campaign query key and mrc_ path in the separate launch workflow.

Validate in the self-service playground

2. Capture and return the Click ID

MeetROAS appends the Click ID to the destination URL. The query key is configured per customer App and defaults to mr_clickid. Read and persist its value, then send that same value in the fixed mr_click_id Partner Event JSON field.

https://casino.example/register?mr_clickid=mrc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Do not parse, modify, or mint this value.
• Do not use the Key ID or Secret as mr_click_id.
• Do not assume every customer uses mr_clickid as the URL key; use the actual campaign URL supplied by that customer.
• Production mrc_ IDs remain valid for 30 days; unknown, expired, or account-mismatched IDs return 404.

End-to-end testing without ad spend

The complete handoff provides an mrt_ for the fixed system test App. Persist it, send it as mr_click_id, and set test: true. MeetROAS validates attribution, schema, and idempotency in Test Runs without source planning, postbacks, or production-performance impact.

https://casino.example/register?mr_clickid=mrt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

test: true must use mrt_. Production requests omit test and use an mrc_ created by real traffic. After testing, remove test; never rewrite mrt_ into mrc_.

3. Build headers and the HMAC signature

1. Serialize the final JSON raw body first.
2. Set timestamp = floor(current_time_ms / 1000).
3. The signing input is timestamp + '.' + raw_body.
4. Compute HMAC-SHA256 with the Secret, encode lowercase hex, then prefix v1=.

1786344000.{"event_id":"payment-123",...}

Send the exact body that was signed. Re-indenting, reordering fields, or adding a newline invalidates the signature. Server time must be within five minutes of UTC.

4. Validate the integration

POST https://api.meetroas.com/v1/events/validate

The validation endpoint applies the same credentials, headers, signature, and schema as production without creating a production event or triggering a traffic-platform conversion.

Choose your server language

Each example serializes the body once, signs those exact bytes, and sends them to the validation endpoint without creating a production event.

import { createHmac, randomUUID } from "node:crypto";

const keyId = process.env.MEETROAS_KEY_ID;
const secret = process.env.MEETROAS_SECRET;
if (!keyId || !secret) throw new Error("Missing MeetROAS credentials");

const body = JSON.stringify({
  event_id: `test-${randomUUID()}`,
  mr_click_id: "mrt_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  event: "deposit",
  occurred_at: new Date().toISOString(),
  value: 49.95,
  currency: "USD",
  test: true,
});
const timestamp = String(Math.floor(Date.now() / 1000));
const digest = createHmac("sha256", secret)
  .update(`${timestamp}.${body}`, "utf8")
  .digest("hex");

const response = await fetch("https://api.meetroas.com/v1/events/validate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-MeetROAS-Key": keyId,
    "X-MeetROAS-Timestamp": timestamp,
    "X-MeetROAS-Signature": `v1=${digest}`,
  },
  body,
});
console.log(response.status, await response.text());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class MeetROASExample {
  public static void main(String[] args) throws Exception {
    String keyId = requireEnv("MEETROAS_KEY_ID");
    String secret = requireEnv("MEETROAS_SECRET");
    String body = String.format(
      "{\"event_id\":\"test-%s\",\"mr_click_id\":\"mrt_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"," +
      "\"event\":\"deposit\",\"occurred_at\":\"%s\",\"value\":49.95,\"currency\":\"USD\",\"test\":true}",
      UUID.randomUUID(), Instant.now());
    String timestamp = Long.toString(Instant.now().getEpochSecond());
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] digest = mac.doFinal((timestamp + "." + body).getBytes(StandardCharsets.UTF_8));
    StringBuilder hex = new StringBuilder();
    for (byte value : digest) hex.append(String.format("%02x", value & 0xff));
    HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.meetroas.com/v1/events/validate"))
      .header("Content-Type", "application/json")
      .header("X-MeetROAS-Key", keyId)
      .header("X-MeetROAS-Timestamp", timestamp)
      .header("X-MeetROAS-Signature", "v1=" + hex)
      .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)).build();
    HttpResponse<String> response = HttpClient.newHttpClient()
      .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode() + " " + response.body());
  }
  private static String requireEnv(String name) {
    String value = System.getenv(name);
    if (value == null || value.isBlank()) throw new IllegalStateException("Missing " + name);
    return value;
  }
}

package main

import (
  "bytes"
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "os"
  "strconv"
  "time"
)

type event struct {
  EventID string `json:"event_id"`
  ClickID string `json:"mr_click_id"`
  Event string `json:"event"`
  OccurredAt string `json:"occurred_at"`
  Value float64 `json:"value"`
  Currency string `json:"currency"`
  Test bool `json:"test"`
}

func main() {
  keyID, secret := os.Getenv("MEETROAS_KEY_ID"), os.Getenv("MEETROAS_SECRET")
  if keyID == "" || secret == "" { panic("missing MeetROAS credentials") }
  body, err := json.Marshal(event{
    "test-" + strconv.FormatInt(time.Now().UnixNano(), 10), "mrt_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "deposit", time.Now().UTC().Format(time.RFC3339), 49.95, "USD", true,
  })
  if err != nil { panic(err) }
  timestamp := strconv.FormatInt(time.Now().Unix(), 10)
  mac := hmac.New(sha256.New, []byte(secret))
  mac.Write(append([]byte(timestamp+"."), body...))
  req, err := http.NewRequest("POST", "https://api.meetroas.com/v1/events/validate", bytes.NewReader(body))
  if err != nil { panic(err) }
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-MeetROAS-Key", keyID)
  req.Header.Set("X-MeetROAS-Timestamp", timestamp)
  req.Header.Set("X-MeetROAS-Signature", "v1="+hex.EncodeToString(mac.Sum(nil)))
  response, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer response.Body.Close()
  responseBody, _ := io.ReadAll(response.Body)
  fmt.Printf("%d %s\n", response.StatusCode, responseBody)
}

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

var keyId = RequireEnv("MEETROAS_KEY_ID");
var secret = RequireEnv("MEETROAS_SECRET");
var body = JsonSerializer.Serialize(new {
  event_id = $"test-{Guid.NewGuid()}",
  mr_click_id = "mrt_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  @event = "deposit",
  occurred_at = DateTimeOffset.UtcNow.ToString("O"),
  value = 49.95,
  currency = "USD",
  test = true,
});
var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var digest = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{timestamp}.{body}"));
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.meetroas.com/v1/events/validate");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");
request.Headers.Add("X-MeetROAS-Key", keyId);
request.Headers.Add("X-MeetROAS-Timestamp", timestamp);
request.Headers.Add("X-MeetROAS-Signature", $"v1={Convert.ToHexString(digest).ToLowerInvariant()}");
using var response = await new HttpClient().SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

static string RequireEnv(string name) => Environment.GetEnvironmentVariable(name)
  ?? throw new InvalidOperationException($"Missing {name}");

{
  "valid": true,
  "authentication": "valid",
  "schema": "valid",
  "event": "deposit",
  "catalog_version": 2,
  "test": true
}

The response catalog_version is the normalized identity version for that event. Existing event shapes retain their original v1/v2 identity so retries of an existing event_id remain stable; read the machine event catalog for the current accepted-catalog version.

The destination engineer can enter the Key ID and Secret in the playground to run the same signing, schema, and rejection checks. The Secret remains only in that browser tab's memory.

5. Send test events, then switch to production

POST https://api.meetroas.com/v1/events

{
  "event_id": "test-93951c0c-446a-4dfb-861e-a9083d453cf4",
  "mr_click_id": "mrt_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "event": "deposit",
  "occurred_at": "2026-09-24T21:12:53.916Z",
  "value": 49.95,
  "price": 0.01,
  "currency": "USD",
  "user_data": {
    "email_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "phone_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "external_id_sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  },
  "client": {
    "ip": "192.0.2.10",
    "user_agent": "Mozilla/5.0 (Example Browser)",
    "page_url": "https://destination.example/complete",
    "referrer_url": "https://destination.example/checkout",
    "meta_fbp": "fb.1.1788480000000.1234567890",
    "tiktok_ttp": "synthetic-test-ttp"
  },
  "test": true
}

user_data / client fields

Both objects and all their fields are optional. Omit unavailable values; do not send null, arrays or unknown fields. Amounts are JSON numbers (49.95, not "49.95"); test is a boolean. The example hashes, IP and cookies are synthetic format examples, not real visitor data to submit. Use actual browser context with the lawful basis and consent for ad measurement.

MeetROAS stores value and price separately and projects them only to semantically matching fields supported by the source. TrafficStars can receive value (revenue) and price (CPA cost); PropellerAds payout, ExoClick value, MGID r, and BidVertiser revenue receive value only; HilltopAds price and Adsterra atpay receive price only; RichAds receives no monetary field. Optional match data is encrypted only in the pending delivery payload and cleared after seven days. Changing money, event semantics, or match data under the same event_id returns 409. Meta/TikTok events must arrive within seven days.

6. Accepted events

The event field must use one of these keys. Use the machine-readable catalog as the authoritative source for automated validation.

A casino or destination sends only the events it actually supports and has enabled; it does not have to implement or send the full catalog. The destination is the producer of each business fact. In particular, the casino determines first_day_deposit, and MeetROAS does not derive or calculate the first day.

GET https://api.meetroas.com/v1/events/catalog

7. Supported traffic platforms

The destination implements the Partner Event API once; MeetROAS connects it to the traffic platform configured by the customer.

8. Responses, retries, and go-live

The limit is 300 requests per 60 seconds for each Key ID and endpoint scope. The raw-body limit is 16384 bytes, timestamp tolerance is 300 seconds, and the recommended client timeout is 10 seconds. A 429 includes Retry-After: 60. Use 2, 4, 8, 16, and 32 second exponential backoff with jitter, for at most five retries; then require investigation without changing event_id or rebuilding the body.

A fixed account test must return integration_status=passed and delivery_readiness=not_applicable. This proves the destination integration without depending on a buyer, Goal Binding, or connector.

1. Obtain credentials and pass the validation endpoint.
2. Use the fixed test mrt_ from the complete package and send the supported event sequence to the production endpoint with test: true.
3. Confirm attribution, schema, duplicate, and conflict semantics in Test Runs; no postback is planned or sent.
4. After real traffic begins, persist the real mrc_, remove the test field, and only then send production business events.

9. Engineering go-live check

This checklist confirms that your backend integration is ready. Once complete, engineers do not change code for each Campaign; the buyer supplies the actual query key and configures Campaigns and conversion events during launch.

10. Security requirements

• Store the Secret only in a server-side secrets manager.
• Never put the Secret in a URL, browser code, support ticket, or application log.
• Use a fresh timestamp for every request and sign the exact raw body that will be sent.
• If a credential is lost or exposed, replace only that destination's Key. Revoke its old Key after the new package is saved; other destinations remain active.