What are Integrator Events?

Integrator Events let you stream customer activity from your own system into AIQ. Any event you track (orders, subscriptions, check-ins, custom actions) becomes a targetable trait you can use to build flows.

For example, an order event like this:

{
  "order_type": "coffee",
  "order_total": 24.50,
  "store_id": "store_1"
}

Lets you build audiences such as:

Customers who have had more than 10 coffee orders in the past 90 days
Customers who had an order with a total greater than $20 from May 1 to May 31
Customers who have orders at both store_1 and store_2

Why use Integrator Events?

Bring your own signals. Any customer activity your system tracks becomes a targetable trait inside AIQ.
No schema setup. AIQ infers the queryable shape of each event automatically from the payloads you send. The first time AIQ sees a field, it becomes available as a trait in the audience builder.

Ingest Endpoint

POST /api/v2/integrators/events/ingest

Headers

Header	Required	Value
`X-APIKEY`	Yes	The AIQ REST API key for the merchant account.
`Content-Type`	Yes	`application/json`

The X-APIKEY both authenticates the request and determines which AIQ account the event is written to. Use the key belonging to the merchant the customer event is tied to.

Request Body

Field	Type	Required	Notes
`integratorSlug`	string	Yes	Your integrator slug, issued by AIQ.
`eventName`	string	Yes	Lowercase slug matching (a–z, 0–9, underscore).
`eventDisplayName`	string	No	Human-friendly label shown in the AIQ UI. Defaults to `eventName`.
`timestamp`	int64	Yes	Unix time in seconds for when the event occurred.
`event`	object	Yes	The event payload. Must be a JSON object.
`phone`	string	One of these four	Contact phone. Normalized by AIQ.
`email`	string	One of these four	Contact email. Normalized by AIQ.
`contactID`	string	One of these four	AIQ contact ID.
`srcID`	string	One of these four	Third-party customer identifier (usually tied to POS).

At least one of phone, email, contactID, or srcID is required so AIQ can resolve the event to a contact.

Limits

Max request body size: 64 KB
Max 20 distinct event names per integrator
Payloads are flattened to a max nesting depth of 3 and a max of 100 fields per payload
JSON keys must be alphanumeric/underscore only

Example Request

curl -X POST https://lab.alpineiq.com/api/v2/integrators/events/ingest \
  -H "X-APIKEY: <merchant-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "integratorSlug": "acme_rewards",
    "eventName": "subscription_renewed",
    "eventDisplayName": "Subscription Renewed",
    "timestamp": 1764709020,
    "email": "[email protected]",
    "event": {
      "plan": { "tier": "gold", "monthly_price": 49.99 },
      "auto_renew": true,
      "promo_codes": ["WELCOME10"]
    }
  }'

Responses

Success

A 200 OK with an empty data object means the event was stored cleanly:

{
  "code": 200,
  "success": true,
  "data": {}
}

Warnings

These flags appear inside data when relevant. If present, some fields may not be queryable in the audience builder.

Flag	Meaning	What to do
`fieldCapReached`	This event already has 100 distinct schema fields; new fields won't become queryable.	Trim the payload to a stable set of meaningful fields. Avoid dynamic or unbounded keys.
`payloadTruncated`	This payload contained more than 100 fields; the overflow wasn't added to the schema.	Reduce the number of fields per event.
`depthTruncated`	The payload nested deeper than 3 levels; deeper fields weren't made filterable.	Flatten nested structures you want to make queryable.
`invalidKeysSkipped`	One or more keys contained characters outside `[A-Za-z0-9_]`; those keys were skipped.	Rename keys to use only letters, digits, and underscores.

Errors

Errors use the standard AIQ evvelope:

{
  "code": 400,
  "success": false,
  "errors": [{ "message": "invalid integratorSlug" }]
}

Status	Example message	Cause
`400`	`integratorSlug is required` / `invalid integratorSlug`	Missing or unknown slug.
`400`	`at least one of phone, email, contactID, or srcID is required`	No customer identifier supplied.
`400`	`eventName is required` / `eventName must be a lowercase slug (a-z, 0-9, underscore only)`	Missing or malformed event name.
`400`	`timestamp is required`	Missing or zero timestamp.
`400`	`event is required` / `event must be a JSON object`	Empty payload or a non-object (array/scalar) `event`.
`400`	`invalid JSON`	Body isn't valid JSON.
`400`	`maximum of 20 unique event types per integrator reached`	Too many distinct event names.
`401`	`missing X-APIKEY header` / `invalid API key`	Auth failure.
`413`	`payload exceeds maximum size of 65536 bytes`	Body over 64 KB.
`500`	`failed to persist event`, `failed to verify integrator`, etc.	Transient server-side issue. Retry the request.

Event Payloads

The event field is the heart of the request. Rules:

Must be a JSON object ({ ... }). Top-level arrays or scalars are rejected.
All keys must be alphanumeric/underscore. Non-conforming keys are skipped from the schema.
null values are ignored.
Nested fields are allowed up to depth 3; deeper levels are dropped from the schema.
Up to 100 fields per payload are added to the schema.

Audience Builder

Once AIQ has received your events, they will show up as traits in the audience builder. Note that these traits are availabe per-account. Traits will only be available in the merchant account once events for that account has been ingested.

You can filter on:

Field values — any field discovered from your payloads becomes a
selectable filter path
Event count — match contacts by how many matching events they have (e.g. exactly 3, more than 5, less than 2).
Time window — a rolling window (e.g. the last 24 hours) or a fixed start/end date
range, evaluated against the event timestamp you sent.