Docs
API Installation

Koah Conversion API

The Koah conversion API is a REST API endpoint to track conversion events on your website.

Prerequisites

  • Access to your Koah advertiser dashboard to retrieve your unique advertiser ID and generate an API key
  • Significant technical skill (web development and HTTP requests) — if that’s not in your wheelhouse, send this guide to a developer

Installation

1

Get your advertiser ID

Log in to your Koah advertiser dashboard, open the Brand tab of the settings page, and copy your advertiser ID.

2

Generate an API key

Go to the API keys tab of your dashboard settings and create an API key.

3

Persist the user ID and Koah click ID

Every event needs a stable user_id, and events from visitors who arrived via a Koah ad need the kad_cid query parameter from that click. Store both so they survive navigation between pages and return visits — server-set HTTP-only cookies work well.

See Identifiers for what each one means and example implementations.

4

Send events to the API

POST a JSON body to https://app.koah.ai/api/v1/conversion_events with an events array of up to 100 events, and the headers Content-Type: application/json and Authorization: Bearer [YOUR_API_KEY].

See the Send events reference for every event field, example requests in several languages, and the response shape.

5

Verify your installation

  1. Visit a page on your site
  2. Trigger the event(s) you set up, e.g. by signing up for an account or buying a product
  3. The Koah installation helper on your dashboard will confirm if the API is integrated correctly and is tracking each event

Identifiers

For Koah to attribute conversions, the conversion API relies on two stable identifiers on each event: user_id and kad_cid.

User ID

user_id is a persistent identifier that stays the same for all events from the same user. It can be any string.

If the user is logged in, use their account ID in your system. Otherwise, use any persistent storage mechanism — cookies, local storage, server-side session state, hidden form fields, persistent URL query parameters — to carry the identifier as they move between pages.

We recommend setting HTTP-only cookies from your server for ease of use, security, and robustness: the initial page view generates a random ID and sends it in a Set-Cookie header, and every later request reads it back. In Ruby on Rails:

cookies.permanent[:koah_capi_user_id] ||= {
    :value => SecureRandom.uuid,
    :httponly => true
}
# Now send the event to Koah conversion API by sending `user_id: cookies[:koah_capi_user_id]`.

Koah click ID

When a user clicks a Koah ad, they land on your website with a kad_cid query parameter identifying the click within Koah's system. The conversion API needs this click ID on subsequent events to trace them back to Koah's ads, both for attribution and internal optimization.

The initial page view can read kad_cid straight from the URL, but the parameter is lost as soon as the user navigates to another page or comes back later. Persist it the same way as user_id; again, server-set HTTP-only cookies are our recommendation. In Ruby on Rails:

if params[:kad_cid].present?
    cookies.permanent[:koah_capi_kad_cid] = {
        :value => params[:kad_cid],
        :httponly => true
    }
end
# Now send the event to Koah conversion API by sending `kad_cid: cookies[:koah_capi_kad_cid]`.

Best practices

  • Test your implementation before launching campaigns
  • Choose the most relevant supported event name that aligns with your business goals
  • Include relevant parameters (like value and currency) for purchase events
  • Check the messages array in every response — the API returns 200 OK even when some events fail validation

FAQ

Was this helpful?