What are First-Party Events?

First-Party Events let you stream customer activity from your own systems (your website, app, POS add-ons, or backend) directly into your AIQ account. 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 First-Party Events?

Bring your own signals. Any customer activity you track becomes a targetable trait inside AIQ.
No integrator required. You send events straight to your own account with your AIQ REST API key. There is no integrator slug to request or include.
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/native/events/ingest

Headers

Header	Required	Value
`X-APIKEY`	Yes	Your AIQ REST API key.
`Content-Type`	Yes	`application/json`

The X-APIKEY both authenticates the request and determines which AIQ account the event is written to.

Request Body

Field	Type	Required	Notes
`eventName`	string	Yes	Lowercase slug (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.

Unlike Integrator Events, there is no integratorSlug field.

Limits

Max request body size: 64 KB
Max 20 distinct event names per account
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/native/events/ingest \
  -H "X-APIKEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "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 envelope:

{
  "code": 400,
  "success": false,
  "errors": [{ "message": "eventName is required" }]
}

Status	Example message	Cause
`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 account reached`	Too many distinct event names on this account.
`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 save event type`, 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 under AIQ Native. These traits are available per account, and only appear once events for that account have 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.

Getting Set Up

Get your AIQ REST API key for the account.
Start sending events to POST /api/v2/native/events/ingest.

Integrator Events vs. First-Party Events

	Integrator Events	First-Party Events
Who sends events	A third-party integrator on behalf of many merchants	The merchant, for their own account
Endpoint	`/api/v2/integrators/events/ingest`	`/api/v2/native/events/ingest`
`integratorSlug`	Required, issued by AIQ	Not used
Event name limit	20 per integrator	20 per account
Onboarding	AIQ creates the integrator	None beyond an API key

Flow Integrator Events (Third Party)

Flow Events (First Party)