API

One endpoint. Send a conversion event, Toplu delivers it to every destination you use. The event schema below follows the IAB Tech Lab's ECAPI 1.0 spec directly, the same fields you'd send to any ECAPI-native destination. The API isn't live yet, this reference describes the intended shape so you know what you're signing up for.

Event

The event object represents a single conversion, a purchase or other action you want reflected in your ad platforms. Every request is authenticated with an API key tied to one account.

Schema

idstring

Your own unique identifier for this event. Strongly recommended, used for idempotency and delivery-status lookups.

timestampinteger

Unix epoch timestamp of when the conversion happened.

event_typeenum

One of ECAPI's 27 standard event types (purchase, add_to_cart, sign_up, and so on), or `custom`.

custom_eventstring

Required only when `event_type` is `custom`.

valuefloat

Monetary value of the event.

currency_codestring

ISO 4217 currency code, required when `value` is set.

sourceenum

Where the event took place: email, website, app, phone_call, chat, physical_store, system_generated, business_messaging, or other.

destinationsstring[]

Which of your connected destinations to deliver this event to, e.g. `["google", "meta"]`.

user_dataobject

Identifiers used to match the event to a person. Hashed fields use SHA-256 over lowercased, trimmed values, the same normalization ECAPI itself specifies.

Send an event

Sends one conversion event for delivery to the destinations you specify. Toplu normalizes it into whatever each destination expects, ECAPI directly where a destination speaks it, a dedicated connector otherwise.

Endpoint

POST https://api.toplu.app/v1/events

Request

curl https://api.toplu.app/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "evt_1a2b3c",
    "timestamp": 1785594720,
    "event_type": "purchase",
    "value": 129.00,
    "currency_code": "USD",
    "source": "website",
    "destinations": ["google", "meta"],
    "user_data": { "email_address": ["5d41402abc4b2a76..."] }
  }'

Response

{
  "id": "evt_1a2b3c",
  "status": "delivered",
  "destinations": {
    "google": { "status": "delivered", "code": 200 },
    "meta": { "status": "failed", "code": 400, "error": "invalid_user_data" }
  }
}

What's next

Authentication, error codes, webhooks, and the full destinations reference are still being written, alongside the API itself. Get in touch if you want early access or want to shape what this should cover.

Need a hand?

Coding is hard sometimes, and that's okay. Visit our help center or reach out directly, we're here to help.

Help centerContact us