Conversion Events

Send events

Record one or more conversion events for your advertiser account.

POST/api/v1/conversion_events

Body parameters

Name
events
Type
object[]
Required
required
Description
An array of up to 100 events. Each event represents a single visitor action such as a page view, sign up, or purchase, and takes the fields listed under Event object.
We recommend sending events in real time, but if you need to batch requests or retry a failed one, you can send several at once.

Event object

Name
advertiser_id
Type
string
Required
required
Description
Your advertiser ID from the Brand tab of your dashboard settings.
Name
event_type
Type
string
Required
required
Description
The name of the event you're sending, e.g. PageView or SignUp. See Events for the full list of supported events.
Name
event_time
Type
integer
Required
required
Description
The Unix timestamp when the event occurred, in either seconds or milliseconds. Measure this on the client if possible to eliminate skew from transport.
Name
action_source
Type
string
Required
required
Description
Set this to website for events on your website. This is the only supported value for now.
Name
user_id
Type
string
Required
required
Description
A persistent user identifier that is the same for all events from the same user. See User ID.
Name
kad_cid
Type
string
Description
The value of the kad_cid query parameter on first page load (present if the user came from clicking a Koah ad), persisted across all events for the same user. Optional, but required for Koah attribution — send it whenever it's available. See Koah click ID.
Name
event_page_url
Type
string
Description
The URL of the page where the event occurred, such as https://yoursite.com/landing.html. Highly recommended.
Name
client_ip_address
Type
string
Description
The IP address of the client browser, either IPv4 or IPv6. You can extract this from the IP header of the request to your server that triggers the event. Highly recommended.
Name
client_user_agent
Type
string
Description
The user agent of the client browser. You can extract this from the User-Agent HTTP header of the request to your server that triggers the event. Highly recommended.
Name
client_screen_width
Type
integer
Description
The width, in pixels, of the client screen. You can read this from JavaScript on the client browser using screen.width. Highly recommended.
Name
client_screen_height
Type
integer
Description
The height, in pixels, of the client screen. You can read this from JavaScript on the client browser using screen.height. Highly recommended.
Name
referrer_page_url
Type
string
Description
The page referrer. You can read this from JavaScript on the client browser using document.referrer. Highly recommended.
Name
event_id
Type
string
Description
A unique ID (idempotency key) for this event. You can use any string, such as a transaction ID or other database record ID specific to the purchase, account, etc, or a randomly generated string. If multiple events with the same event ID are received, Koah de-duplicates them to a single event. Highly recommended, and required if you use both the pixel and the API — see de-duplicating events.
Name
event_parameters
Type
object
Description
Event-specific parameters such as the monetary value and currency of products purchased. Whether this is required depends on the event type — see Events for the parameters each event type expects.

Headers

Name
Authorization
Type
string
Required
required
Description
Bearer [YOUR_API_KEY], using an API key generated from your advertiser dashboard.
Name
Content-Type
Type
string
Required
required
Description
Must be application/json.

Response

The API returns 200 OK with a JSON body.

Name
events_received
Type
integer
Description
The total number of events in the request body.
Name
messages
Type
array
Description
Validation errors, one entry per invalid event. Empty when every event was accepted.
Name
messages[].index
Type
integer
Description
The position of the offending event in the events array.
Name
messages[].message
Type
string
Description
A description of what was wrong with that event.

The API returns 200 OK even if some events have validation errors, so always check messages.

Rate limit

The API allows 100 requests per second per IP address. Each request can carry up to 100 events, so batch events into a single request if you're approaching the limit.

curl -X POST https://app.koah.ai/api/v1/conversion_events \
  -H "Authorization: Bearer [YOUR_API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "advertiser_id": "YOUR_ADVERTISER_ID",
        "event_type": "SignUp",
        "event_time": 1787358385,
        "action_source": "website",
        "user_id": "78fec301-d5b2-44d5-9129-825337318519",
        "kad_cid": "42b92bda-ac34-4bb4-be58-7629fbf0eb23",
        "event_page_url": "https://www.koahlabs.com/advertise",
        "client_ip_address": "172.16.254.1",
        "client_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "client_screen_width": 1200,
        "client_screen_height": 800,
        "referrer_page_url": "https://www.google.com",
        "event_id": "b2f9bbdd-ce56-4c90-8241-9afed6c4eff7",
        "event_parameters": {
          "currency": "USD",
          "value": 25.0,
          "products": [
            {
              "id": "123",
              "name": "Koah Premium Subscription",
              "category": "Subscription"
            }
          ]
        }
      }
    ]
  }'

Response

{
  "events_received": 2,
  "messages": [
    {
      "index": 1,
      "message": "Missing required field(s): user_id"
    }
  ]
}