Back to docs
API Reference

Event Ingestion API

Send exposures and conversions from your own systems so A/B tests count conversions that happen off your Flint site.

Overview

Your most important conversions often happen somewhere else: a signup in your app, a purchase in your store, a deal in your CRM. The Event Ingestion API lets you send those to Flint from your own systems, such as a data warehouse, Segment, or your server, so Flint can tie them to the version of the page each visitor saw.

You send two kinds of events:

  • •Exposures. A visitor saw a version of a page in an A/B test.
  • •Conversions. That same visitor signed up, bought something, or did whatever counts as a win.

Flint matches the two on visitor_id.

Base URL

text
https://app.tryflint.com/api/ingest/sites/{siteId}

Before you start

You need three things:

  1. 1.Your site ID. Open your site in Flint. It's the siteId value in the address bar: app.tryflint.com/app/edit?siteId=<your site ID>.
  2. 2.The experiment and version IDs. When a visitor lands on a page in a running test, Flint adds two parameters to the URL: utm_extra3 identifies the experiment and utm_extra4 identifies the version (control for the Control). Send those values as experiment_id and variation_id. To see them for a test, ask Flint: "List the experiment ID and the ID of each version for my test on /pricing." If Flint renamed these parameters for your site, use the renamed ones.
  3. 3.A visitor ID. A stable, anonymous ID for each visitor that your systems already have, such as Segment's anonymousId or your own first-party cookie. Use the same ID in a visitor's exposure and conversion. Don't use an email address or a name.

Authentication

No API key is needed. Send JSON with a Content-Type: application/json header.

Send an exposure

Send one exposure each time a visitor sees a page in a test. Sending more than one for the same visitor is fine: Flint uses the earliest.

text
POST https://app.tryflint.com/api/ingest/sites/{siteId}/exposures
FieldTypeDescription
visitor_idstringThe visitor's anonymous ID.
experiment_idstringThe utm_extra3 value, like c9581a29.
variation_idstringThe utm_extra4 value, like 0c176676, or control.
timestampstringWhen the visitor saw the page, in ISO 8601 with a time zone, like 2026-11-17T21:20:00Z.

All fields are required.

bash
curl -X POST "https://app.tryflint.com/api/ingest/sites/$SITE_ID/exposures" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_id": "9f970770-35a8-4e6d-93e0-b0e5d058a70a",
    "experiment_id": "c9581a29",
    "variation_id": "0c176676",
    "timestamp": "2026-11-17T21:20:00Z"
  }'

Send a conversion

Send one conversion for each signup, purchase, or other goal.

text
POST https://app.tryflint.com/api/ingest/sites/{siteId}/conversions
FieldTypeDescription
visitor_idstringThe same anonymous ID you sent with the visitor's exposure.
event_namestringWhat happened, like signup or purchase.
conversion_idstringA unique ID for this conversion, like your order ID or signup ID.
timestampstringWhen the conversion happened, in ISO 8601 with a time zone.
revenuenumberOptional. The value of the conversion, like 90.92. A numeric string such as "90.92" also works.

visitor_id, event_name, conversion_id and timestamp are required. If revenue is missing, negative, or not a number, Flint records the conversion without a value.

bash
curl -X POST "https://app.tryflint.com/api/ingest/sites/$SITE_ID/conversions" \
  -H "Content-Type: application/json" \
  -d '{
    "visitor_id": "9f970770-35a8-4e6d-93e0-b0e5d058a70a",
    "event_name": "purchase",
    "conversion_id": "order_10482",
    "timestamp": "2026-11-17T21:34:12Z",
    "revenue": 90.92
  }'

Responses

StatusBodyMeaning
200{"status":"recorded"}Flint stored the event.
200{"status":"duplicate"}Flint already has a conversion with this event_name and conversion_id, so it ignored this one.
400{"error":"invalid_payload", ...}A field is missing or malformed. fieldErrors names each field and what's wrong with it.
404{"error":"site_not_found"}No Flint site has this ID. Check the site ID in the URL.
429Too many requests. Wait and retry.

A 400 is never stored, so fix the payload and send it again.

Retries and duplicates

  • •Conversions are safe to retry. Flint keeps one conversion per event_name and conversion_id, so a retry returns duplicate instead of counting twice.
  • •Exposures are safe to retry. Flint counts each visitor once per experiment, using their earliest exposure.
  • •Retry on 429 and 5xx with a backoff. Don't retry a 400 or 404 unchanged; it will fail the same way.
  • •Order doesn't matter. A conversion can arrive before its exposure.

Limits

  • •One event per request.
  • •100 requests per minute from one IP address. For a large backfill, spread the requests out.
  • •IDs and event names are up to 200 characters.

Privacy

Send only anonymous IDs. Don't put names, email addresses, phone numbers, or health information in any field. Flint stores only the fields listed above and drops anything else in the body. When a request is rejected, Flint logs which fields failed, never their values.

Test your setup

  1. 1.Send one exposure and one conversion with the same visitor_id, using the curl examples above with your site ID and IDs.
  2. 2.Check that both return 200 with {"status":"recorded"}. Send the same conversion again and check that it returns {"status":"duplicate"}.
  3. 3.Turn on your forwarder and check its logs for any status other than 200. A 400 body names the field to fix.

Test events are stored like real ones, so use a handful of test visitors and tell your Flint contact which visitor_id values were tests.

Set it up with your AI assistant

Give your coding assistant this page and your IDs, and it can build and test the forwarder for you:

Forward A/B test events to Flint

Following https://www.flint.com/docs/event-ingestion, send our A/B test exposures and conversions to Flint from <Segment / our warehouse / our server>. Site ID: <your site ID>. Exposures come from page views whose URL has utm_extra3 and utm_extra4; conversions are <signup and purchase events>. Use <our anonymous visitor ID> as visitor_id. Send one test exposure and conversion, show me the responses, and fix anything that doesn't return 200 recorded.