Send customer events

A customer event records one thing a person did, such as completing an order or starting a trial. You send events with the Track API. In JustAI, events start and move journeys, personalize messages, and measure conversions. This page covers how to send an event, how to name it, what to put in it, how to tie it to a person, and how to confirm that JustAI received it.

Segment, RudderStack, and Hightouch send the same Track request for you, so the rules on this page apply to them too. See Choose a data source.

Before you begin

Create an API key while the environment you send to is selected. Open the account menu, select Settings > API keys, and select New key. Keep the key on your servers. Never put it in browser or mobile app code.
Get your organization slug from your JustAI team.
Send each person’s profile with the Identify API. Track records events but does not create or update profiles.

What events do in JustAI

Start journeys. A journey whose entry is Event triggered starts when a matching event arrives.
Move journeys forward. A Wait until step can hold a person until one of your events arrives.
End journey runs. An exit rule under Exit conditions can end a run the moment a matching event arrives.
Personalize messages. Event merge tags read properties from the event that started the journey (Journey starting event) or from the person’s most recent event (Latest event for recipient).
Measure results. Pick an event as a journey’s Key metric under Measurement. JustAI counts a conversion when the same person, matched by user ID, sends that event after entering the journey and within the attribution window.

A journey reacts to an event only when all of these are true:

The journey is published, and the event arrived after it was published.
The event name matches the name in the journey exactly, including case.
The event has a non-empty userId. Events with only an anonymousId never reach journeys.

After you publish a journey, wait about a minute before you send a test event. Events that arrive in the first moments after publishing can miss the journey. To check that an event reached a journey, see Confirm that an event reaches a journey.

The journey event picker reads the Events > Custom events list, which shows event names received in the last 30 days. Send one test event with the exact name, wait until it appears in Custom events after processing, and then build the journey. Only the picker waits for this list. Once a journey is published, its triggers, waits, and exits react to new events without that delay.

Events do not feed segments. Segments match people by profile traits. To group people by what they did, keep a summary trait on the profile, such as last_order_date, and update it with Identify.

Send a Track request

Send the event in a POST request:

POST https://ingest.justwords.ai/api/track/{org_slug}
X-Api-Key: YOUR_API_KEY
Content-Type: application/json

{
  "type": "track",
  "messageId": "order-5678-completed",
  "userId": "user-1234",
  "event": "Order Completed",
  "timestamp": "2026-10-12T15:04:05Z",
  "properties": {
    "order_id": "order-5678",
    "value": 49.5,
    "currency": "USD",
    "item_count": 2
  }
}

JustAI returns 202 when it has accepted the event:

{
  "message_id": "order-5678-completed",
  "status": "accepted"
}

Field	Required	Description
`type`	Yes	Always `"track"`.
`messageId`	Yes	A unique ID for this action, as a string.
`event`	Yes	The event name.
`timestamp`	Yes	When the action happened, in ISO 8601 with `Z` or an offset.
`userId`	Yes, unless you send `anonymousId`	Your user ID for the person, as a string.
`anonymousId`	No	An ID for a person you can’t identify yet.
`properties`	No	An object with details of the action.
`context`	No	An object stored with the event.

JustAI ignores other top-level fields, so it accepts a full Segment or RudderStack track payload as it is. Send one event per request. An array or a {"batch": [...]} body returns 400. Do not end the URL with a slash, because a trailing slash returns 404. For a non-production environment, use its path value in place of {org_slug} and send its environment key in the X-JustAI-Environment header, as described in the API overview.

A 503 with {"error":"Event storage is unavailable"} is temporary. Retry with the same body and messageId. For every status code, see Errors and retries. For every field rule, see the Track API reference.

Name your events

JustAI matches event names exactly. Case, spaces, and punctuation all count, so Order Completed, order completed, and order_completed are three different events.

Pick one naming style and use it in every source.
Describe what the person did, in the past tense: Order Completed, Trial Started, Plan Upgraded.
Trim names before you send them. JustAI keeps leading and trailing spaces, so Order Completed with a trailing space is a different event from Order Completed. Never send a blank or space-only name.
Do not use profile_fields_changed or subscription_changed. JustAI uses those names for its own events.

A renamed event is a new event. Journeys and key metrics that use the old name stop matching until you update them.

Add properties

Put the details of the action in the properties object, such as an order ID, an amount, or a plan name. Values can be any JSON value.

Keep each property’s type the same in every event. Only when conditions in a journey compare values by type, so the text "14" does not match the number 14.
properties, context, and integrations must be objects if you send them. null or an array returns 400.
JustAI stores context with the event as you send it, including any IP address or user agent it contains. Send only the context fields you need.
Keep each event well under 1 MB. JustAI counts a larger size than your request body, especially when values contain many quotes. A larger event returns 413 with {"error":"Track event is too large"}.
For events that drive journeys, keep the properties and IDs together under 128 KB, and nest properties no more than 100 levels deep. Leave the null character (\u0000) out of property values. JustAI still accepts and records an event that breaks these limits, but no journey reacts to it.

Identify the person

Send userId with the same user ID you use in Identify. JustAI matches it to the profile character for character. Identify removes leading and trailing spaces from the user ID, but Track stores it as sent, so trim IDs before you send them.

A journey looks up the person by userId. If no profile has that user ID, the run starts without the person’s traits or email address, and email steps can’t send to them. Send Identify for each person before their first event.

Track also accepts anonymousId for people you can’t identify yet. An event needs at least one of userId or anonymousId. An event with only anonymousId appears in Events > Custom events, but it never starts or moves a journey and never counts as a conversion. JustAI does not link anonymous events to a profile later. See Identity and consent.

Set the message ID and timestamp

Track requires both fields.

messageId is the event’s identity. Use a new, unique messageId for every action, and reuse it only to retry the same event. JustAI counts events that share a messageId once, and the event starts a journey at most once, however many times you retry it. The API returns 202 for a repeated messageId too, and it does not report duplicates.

Do not reuse a messageId to change an event. JustAI can’t edit or delete an accepted event. If you send a corrected event with a new messageId, JustAI records it in addition to the original, and it can start a matching journey again. To remove events, contact your JustAI team.

timestamp is when the action happened, not when you send it. Use an ISO 8601 string with Z or an offset, such as 2026-10-12T15:04:05Z. A time without a time zone, a space instead of T, or a number returns 400.

Load past events

Send only live events through the Track API. JustAI handles every Track event as a new event, whatever its timestamp, so a replayed past event whose name matches a published journey starts or advances that journey.

Contact your JustAI team before planning an import of past events. Confirm availability, how those events would be used, and how you would verify the result before exporting or sending them.

Find events in JustAI

Open Events in the left sidebar. Check that the account menu shows the environment you sent to.

Events > Custom events lists the event names your systems have sent through the Track API, with Name, Attributes, First seen, and Last seen. First seen and Last seen are the times JustAI received events with that name, not your timestamp values. Select a name to see Recent events, which lists individual events and the user each came from, and Attributes, which lists each property and its type from the last 30 days.

The list shows events received in the last 30 days. To see older names, open the filter menu and select Include inactive.

New events can take time to appear in Custom events. Select Refresh to reload the list. If an accepted event still doesn’t appear after you refresh, contact your JustAI team with its messageId. Do not resend it. The same delay applies to Last seen, Recent events, Latest event for recipient merge tags, and conversion counts. Journey triggers, waits, and exits do not wait for it.

Events > Activity lists the changes and events that journeys react to, such as profile changes and subscription changes. A Track event appears there only when a published journey uses its name. Use Custom events to confirm that an event arrived.

Check your work

Send one event for a test user who already has a profile. Expect 202, with a message_id that matches your messageId.
Allow time for processing. Then open Events > Custom events and select Refresh. The event name appears in the list.
Select the event name. Under Recent events, find the event from your test user.
When your marketing team publishes a journey on the event, confirm that the event reaches it. Follow Confirm that an event reaches a journey.

For a full walkthrough with curl, see Test your connection.

Next steps

Choose a data sourceFind the source guide for your CDP, warehouse, or backend.

Connect IterableAdd your Iterable project, content data feed, system webhook, and a sending profile.

Track API referenceEvery field, rule, and error for Track.