Events API

An event is a fact your system reports to Hamla: something happened, to a specific person, at a specific time. Once stored it can start a campaign, define an audience, end a sequence, and move the contact through their journey. For the guided version, read Hamla Events. This page is the contract.

The doors

Three carry events. The fourth carries the person they happened to.

Door	Use it for	Key	Can start a campaign
`POST /api/sdk/track`	one live event from your server	secret, required	Yes
`POST /api/sdk/track/batch`	up to 500 past events (backfill)	secret, required	No — never
`hamla.track()` in the browser	a deliberate action inside your page	none	Yes
`POST /api/sdk/identify`	who someone is, and what to call them	optional	—

Passive autocapture — page views, scrolls, idle timers gathered by the script tag on its own — is another stream. It feeds analytics and behavioral triggers, but it never opens an event trigger. Deliberateness is never guessed from the event name.

Authentication

track and track/batch require a secret key:

Authorization: Bearer sk_live_xxx

Create one in Settings → API keys. Older hamla_live_… keys keep working. A publishable key (pk_live_…) authenticates but is refused with 403 on these endpoints: it ships in page source, so honoring it would let any visitor invent revenue. Neither endpoint sends CORS headers or answers OPTIONS, deliberately — a page that cannot pass CORS cannot be tempted to embed a secret key. The key names exactly one business. businessId in the body is optional; if present and it disagrees with the key, the request is refused rather than quietly rewritten.

POST /api/sdk/track

Records one event that just happened.

curl -X POST https://app.hamla.io/api/sdk/track \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "subscription_started",
    "identity": { "email": "omar@raqmi.co", "platformCustomerId": "user_812" },
    "properties": { "plan": "pro", "seats": 3 },
    "value": 29,
    "currency": "JOD",
    "occurredAt": "2026-08-23T09:41:00Z",
    "idempotencyKey": "invoice_9911",
    "traits": { "plan": "pro", "subscription_status": "active" },
    "tags": ["paying"]
  }'

Fields

Field	Type		Notes
`event`	string	required	The moment, in your own vocabulary. Trimmed, 1–64 characters. Matched exactly by triggers and segments.
`identity`	object	required	At least one of `email`, `phone`, `platformCustomerId`. See below.
`occurredAt`	string \| number	optional	ISO 8601 or epoch milliseconds. Defaults to now. The past is allowed; more than 5 minutes into the future is rejected.
`type`	string	optional	What the event MEANS, from the list below. Omit it and Hamla infers.
`value`	number	optional	Finite. Counts toward the contact’s revenue — see What an event means.
`currency`	string	optional	1–8 characters, e.g. `JOD`, `SAR`, `USD`.
`properties`	object	optional	Any JSON detail worth keeping with the event. Max 32,768 bytes serialized. Stored nested, never spread into the payload root.
`tags`	string[]	optional	Merge-added to the contact — never replaces existing tags. Max 50 tags, each 1–64 characters.
`traits`	object	optional	Current-state values written to custom fields. Values may be string, number, boolean or null. Unknown keys are created automatically.
`idempotencyKey`	string	optional	1–200 characters. Re-sending with the same key is a recorded no-op.
`businessId`	string	optional	Cross-check only. Must match the key’s business.
`visitorId`	string	optional	Links the event to a known browser session, when your server happens to have the cookie. Max 128 characters.
`context`	object	optional	The person’s own device and whereabouts — `userAgent`, `country` (ISO-2), `region`, `city`. Worth sending on the first event about someone, because that call creates their contact: without it, a customer born from a `purchase` has no country and no device. Same shape and same rules as identify’s, below. A malformed value comes back as a `warnings` entry — never a refused event.

`identity`

Field	Type	Notes
`email`	string	3–320 characters.
`phone`	string \| number	Any format you store.
`platformCustomerId`	string \| number	Your own user id.

Any one is enough, and it does not have to be the email — a business that only ever collects phone numbers sends phone alone, forever. An event with no identity at all belongs to nobody and is refused. Send more than one and Hamla uses them together to match or create a single contact, keeping each as a way to find that person later. Anonymous browsing history joins the profile at the moment identity is first known. Identity is recognition, not permission: a phone number lets Hamla match someone, and never doubles as consent to send them an SMS or WhatsApp message.

Response

{
  "success": true,
  "message": "Event recorded",
  "data": {
    "contactId": "cm4x...",
    "event": "subscription_started",
    "isNew": false,
    "deduped": false,
    "interpreted": { "type": "purchase", "countedRevenue": 29 },
    "warnings": ["custom field \"businesses_count\" needs a number — skipped"]
  }
}

Field	Meaning
`contactId`	The contact this event landed on.
`isNew`	`true` when this call created the contact.
`interpreted`	What Hamla decided the event means, and how much of `value` it counted.
`deduped`	`true` when `idempotencyKey` matched an event already recorded. Tags and traits are still applied, so a retry converges to the same state.
`warnings`	Present only when something advisory happened — usually a trait that did not match its field’s type.

Errors

Status	When
`400`	Malformed JSON, schema violation, no identity field, bad `occurredAt`, oversized `properties`.
`401`	No `Authorization` header, or the key is invalid or revoked. The two answer differently.
`403`	Publishable key, `businessId` mismatch, or the business is not active.
`404`	Business not found.
`429`	Rate limit exceeded. Retry after the window in the response headers.

POST /api/sdk/track/batch

Records up to 500 events that already happened. Same event vocabulary, same field rules, same secret key.

curl -X POST https://app.hamla.io/api/sdk/track/batch \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event": "purchase", "identity": { "email": "omar@raqmi.co" },
        "value": 120, "currency": "JOD",
        "occurredAt": "2025-11-02T10:00:00Z", "idempotencyKey": "order_5512" },
      { "event": "purchase", "identity": { "email": "lina@example.com" },
        "value": 80, "currency": "JOD",
        "occurredAt": "2025-12-14T18:20:00Z", "idempotencyKey": "order_5610" }
    ]
  }'

events takes 1–500 items. Each item accepts every track field except visitorId and context — replayed history carries no browser session and no live request, so nothing saw a User-Agent or a country.

What backfill deliberately does not do


No campaign fires.	Imported events carry no trigger marker at all. A thousand year-old purchases must not send a thousand messages tonight.
No segment-entry blast.	Segment recomputes from an import run in bulk: membership moves, entry triggers stay silent.
No web attribution.	History replayed from a database is not a web arrival, so visitor state is untouched.

Everything a backfill should do still happens: contacts are resolved or created, activities land with their real occurredAt, first/last/count statistics update (out-of-order rows are handled), traits and tags apply, and value counts toward revenue.

Response

Items fail alone — a bad row reports its index and reason, and the rest of the batch lands.

{
  "success": true,
  "message": "Batch recorded with failures",
  "data": {
    "received": 500,
    "recorded": 497,
    "deduped": 2,
    "failed": 1,
    "failures": [{ "index": 314, "error": "occurredAt cannot be in the future" }],
    "warnings": ["events[12]: custom field \"plan\" needs a number — skipped"]
  }
}

warnings is capped at 50 entries so one misnamed column across 500 rows cannot dominate the response. Give every row an idempotencyKey and the whole import is safe to re-run.

POST /api/sdk/identify

Says who someone is — and what to call them. The companion to track: identity and profile, no event. It shows on the person’s timeline as identified, which is never a form, a lead or a conversion. Calling it on every page a signed-in person loads is safe.

curl -X POST https://app.hamla.io/api/sdk/identify \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": { "email": "omar@raqmi.co" },
    "profile": { "name": "Omar Al Saleh", "country": "JO" },
    "method": "signup"
  }'

Resolve-or-create: an unknown person becomes a contact, a known one is enriched. Safe to call on every login — profile fields are gap-filled, never overwritten.

Fields

Field	Type		Notes
`identity`	object	required	Same three fields, same rules, as `track`’s above.
`profile`	object	optional	Name and location. See below.
`traits`	object	optional	Current-state values → custom fields. Secret key only — an unkeyed caller’s traits are ignored with a `warnings` entry, because an anonymous claim about someone’s plan is not a fact.
`method`	string	optional	Your label for the door they came through: `signup`, `checkout`, `google`. Max 64 characters, recorded on the signal. It is what tells “nobody signed up today” apart from “the checkout identify stopped firing”.
`visitorId`	string	optional	The Hamla visitor cookie, linking their anonymous browsing — including the ad click that brought them — to this person. The browser SDK sends it for you; a server can read the cookie and pass it.
`context`	object	optional	The person’s own device and whereabouts, when the caller is your server. Secret key only. See below.
`businessId`	string	optional	Cross-check only. Must match the key’s business.

`profile`

Field	Notes
`name`	The whole name in one string. Split on arrival: first word → `firstName`, the rest → `lastName`, so `Sara Al Otaibi` is greeted as Sara.
`firstName` / `lastName`	Send these instead when your database already keeps them apart. Sent alongside `name`, they win field by field.
`country`, `city`	Free-form; used for location segments.
`language`	The language campaigns to this person should be written in.
`timezone`	IANA zone, e.g. `Asia/Amman`. Keeps a delayed campaign step out of the recipient’s night. The browser SDK fills it in; a country alone cannot answer it for anyone in the US, Brazil, Canada or Australia.

Worth sending a name for one reason: {{contact.firstName}} in a campaign. Without it every message opens with Hi Friend.

`context` — for signups that happen on your server

Field	Notes
`userAgent`	Their User-Agent, verbatim. Device, OS and browser are read from it.
`country`	ISO-3166-1 alpha-2, e.g. `SA`, `RW`.
`region`, `city`	As your host reports them.

The browser SDK needs none of this: its request is the person, so Hamla reads the device and the country off it directly. A signup that completes on your server is the opposite — the request Hamla receives comes from your data centre. Without context that contact has no device and no country at all, and it is not a small gap: “which countries are my customers in” and “how many sign up on a phone” have no answer for anyone who signed in through an OAuth callback, a server-rendered form, or a mobile app. Read the values off the request the person actually made — user-agent, and whichever geo header your host adds (x-vercel-ip-country, cf-ipcountry):

await hamla.identifyNow({
  identity: { email: user.email },
  method: 'google',
  context: {
    userAgent: request.headers.get('user-agent') ?? undefined,
    country: request.headers.get('x-vercel-ip-country') ?? undefined,
  },
});

Requires a secret key, for the same reason traits does: this is a claim about someone. From an unkeyed caller it is ignored with a warnings entry, and the request’s own headers are used instead. Send no context and Hamla records nothing rather than guessing — your hosting region is not where your customer lives. Geo is taken as country/region/city rather than as an IP address on purpose: Hamla keeps the place, never the address.

Authentication, unusually

This is the one write endpoint that also serves unkeyed callers, because published browser bundles cannot send an Authorization header and cannot be upgraded once a customer’s CDN has them. A key is still worth sending from a server: it scopes the write to your business and makes it attributable, and traits require one.

Response

{
  "success": true,
  "message": "New contact created and linked",
  "data": {
    "contactId": "cm4x...",
    "isNew": true,
    "linkedVisitor": true,
    "subscriptions": { "email": true, "sms": false, "whatsapp": false, "push": false },
    "warnings": []
  }
}

linkedVisitor is true when this call is what tied the anonymous browser to the person — the moment their earlier visits, and the campaign that produced them, stop being anonymous. warnings is absent when everything landed.

hamla.track() — the browser door

For deliberate actions that genuinely happen in the page. No key, because none can safely ship to a browser.

hamla.track('download_ebook', { asset: 'guide.pdf' });
hamla.track('appointment_booked', { date: '2026-04-15', price: 100 });

The event name is used verbatim. Because the page’s own code chose to send it, it counts as deliberate and can start a campaign — unlike the autocapture events travelling in the same batch. Anything involving money or your own records belongs on the server door, where the key lives and the facts cannot be edited by a visitor.

What an event does once stored

Surface	Where	Behavior
Campaign trigger	When does the campaign start? → App event → Your app’s events → Event name	Fires for every matching event from now on. Enrollment is once per contact unless Can enter again later is on. Names can be typed before the event has ever arrived.
Segment rules	Segment builder → Events	Two fields per event name — see below. The group appears once the first event exists.
Conversion goal / end of sequence	How the sequence ends → When an event happens	Whoever fires it stops receiving the rest, checked before every send. Locks after publish.
Journey stage	Contact profile	Only for the recognized names below.
Timeline	Contact profile	Every event, kept with its `occurredAt`.
Analytics	Reports and attribution	Feeds engagement, scoring, metrics, and Meta conversion forwarding.

Segment fields

Path	Reads	Operators
`event.<name>`	when it last happened	Date operators — `exists` (ever), `not_exists` (never), `within_days`, `older_than_days`
`event.<name>.count`	how many times	Number operators
`event.<name>.first`	when it first happened	Date operators. Evaluated but not offered in the picker.

A contact with no matching event resolves to undefined for all metrics, including count. So “fewer than 5 times, including never” is count < 5 OR not_exists — never a silent zero.

Names that move the journey stage

Your own names are recorded and fully usable; they simply do not move the stage. Borrow these when they fit:

Stage	Event name
New	`page_view`, `inbound_message`, `lead_submitted`, `form_submitted`, `email_opened`, `manual_contact_created`, `imported`
Interested	`email_clicked`, `whatsapp_replied`, `product_viewed`, `add_to_cart`, `booking_started`, `pricing_page_viewed`, `checkout_started`, `trial_started`
Customer	`appointment_booked`, `subscription_started`, `purchase`, `deal_won`, `booking_confirmed`, `reservation_confirmed`, `invoice_paid`
Regular	`order_delivered`, `appointment_attended`, `subscription_renewed`, `repeat_purchase`, `product_reviewed`
Fan	`referral_made`, `review_5_star`, `ugc_posted`, `affiliate_signup`

An email click Hamla records is read by where its link goes. A click toward your business (your site, product, booking page, app store, or a chat with you) is Interested. A click on a social profile counts as engagement and leaves the stage where it is. An unsubscribe click, or a mail scanner opening every link within seconds, moves no one. An email_clicked you send yourself always counts.

What an event means

event is your word. type is ours, and there are eleven of them. You never have to send type — Hamla infers from the amount and from names it already recognises. Send it and nothing is guessed.

`type`	What it means	Revenue	Counts as an order
`purchase`	Money received	+ `value`	Yes
`refund`	Money returned	− `value`	No
`booking`	Committed, not yet paid	—	No
`lead`	Identity captured	—	No
`checkout_started`	Started, not finished	—	No
`fulfilled`	They received it	—	No
`cancelled`	It ended	—	No
`signup`	Account created	—	No
`trial`	Free trial started	—	No
`contact`	Reached out	—	No
`application`	Applied	—	No

{
  "event": "treatment_completed",
  "type": "purchase",
  "identity": { "phone": "+962790000000" },
  "value": 100, "currency": "JOD"
}

A clinic calls it treatment_completed, a school calls it lesson_finished, and both are a purchase. Your name is never translated, replaced or checked against a list — it is kept exactly as you sent it, and stays what your reports, segments and triggers are written in.

booking is the one worth knowing about. Every other analytics vocabulary was designed for online stores, where saying yes is paying. A confirmed appointment and a signed contract are real commitments that move no money — so they are a booking, not a purchase, and they will not show up in revenue or inflate your average order value. When one of them does carry an amount, send the amount and Hamla counts it.A free trial is not a booking: trying is not paying. trial_started is checkout_started — started, not finished — so a trial user is Interested, and becomes a Customer at their first payment.

What your ad accounts hear

When Google Ads or Meta is connected, Hamla tells them which results their ad clicks produced, by type and never by your event’s name: purchase (with the amount), booking, lead, signup, trial, contact and application each reach Google as their own conversion action and Meta as its standard event (Purchase, Schedule, Lead, CompleteRegistration, StartTrial, Contact, SubmitApplication). So treatment_completed sent with type: "purchase" reaches your ad account exactly like a store’s purchase. Imported history is never reported.

If you send nothing

Hamla decides in this order:

type, if you sent it. Always wins.
A value. Money moved, whatever you called the event. A negative amount is a refund.
A name Hamla already knows. Kept so that integrations written before type existed keep behaving exactly as they did.

If none apply, the event is still recorded, still segmentable and can still start a campaign — it just does not claim to be revenue. These are the names in full. You never need them — type says the same thing in any vocabulary — but nothing you already send changes meaning because of them.

`type`	Names Hamla still recognises
`purchase`	`deal_won`, `invoice_paid`, `purchase`, `repeat_purchase`, `subscription_renewed`, `subscription_started`
`booking`	`appointment_booked`, `booking_confirmed`, `reservation_confirmed`
`lead`	`form_submitted`, `hamla_form.submitted`, `hamla_link.submitted`, `lead_submitted`
`checkout_started`	`add_to_cart`, `booking_started`, `checkout_started`, `trial_started`
`fulfilled`	`appointment_attended`, `order_delivered`
`cancelled`	`appointment_cancelled`, `subscription_canceled`, `subscription_expired`

An amount is never counted silently. If you send a value and Hamla cannot tell what it means, the response says so in warnings rather than storing it and moving on. Every response also echoes interpreted, so you can see the decision on your first request instead of in a report weeks later.

Traits and custom fields

traits writes the contact’s current state; the event records what happened. Send both in one call. The first time a trait key arrives, Hamla creates the matching custom field and infers its type: 3 becomes Number, true Boolean, "2026-08-08" Date, anything else Text. It shows up in Contacts → Contacts Management → Custom Fields and segments can filter on it immediately. Two rules, both reported in the warnings array:

Keys are snake_case — businesses_count, not Businesses-Count.
A field keeps its first type. Once businesses_count is a Number, a later "lots" is skipped rather than corrupting what is stored.

Limits


Event name	1–64 characters
`properties`	32,768 bytes serialized
`tags`	50 per request, 1–64 characters each
`idempotencyKey`	1–200 characters
`occurredAt`	any past time; max 5 minutes ahead
Batch size	500 events per request
Rate limit	120 requests per minute, per business — a batch request costs one unit regardless of how many events it carries

The rate limiter fails open: if it is unreachable, requests are allowed rather than rejected.

Node SDK

npm install @gethamla/node wraps the same endpoints — nothing it can do is unavailable over plain HTTP.

import { Hamla } from '@gethamla/node';
const hamla = new Hamla(); // reads HAMLA_API_KEY

hamla.identify({ identity: { email: 'omar@raqmi.co' }, profile: { name: 'Omar Al Saleh' } });
hamla.track({ event: 'subscription_started', identity: { email: 'omar@raqmi.co' } });

await hamla.trackNow({ event: 'purchase', identity: { email: 'omar@raqmi.co' } }); // awaited
await hamla.trackBatch(historicalEvents);                                          // chunked replay
await hamla.flush();                                                               // serverless: drain before freeze

track and identify are fire-and-forget and never throw — a marketing call must not break a checkout. trackNow returns a DeliveryResult when you want to know. trackBatch re-bases failure indexes onto your own array, and refuses visitorId for the same reason the endpoint does.

Start here

Ask Hamla

Get results

Your customers and data

Check and fix

Reference

The doors

Authentication

POST /api/sdk/track

Fields

`identity`

Response

Errors

POST /api/sdk/track/batch

What backfill deliberately does not do

Response

POST /api/sdk/identify

Fields

`profile`

`context` — for signups that happen on your server

Authentication, unusually

Response

hamla.track() — the browser door

What an event does once stored

Segment fields

Names that move the journey stage

What an event means

What your ad accounts hear

If you send nothing

Traits and custom fields

Limits

Node SDK

​The doors

​Authentication

​POST /api/sdk/track

​Fields

​identity

​Response

​Errors

​POST /api/sdk/track/batch

​What backfill deliberately does not do

​Response

​POST /api/sdk/identify

​Fields

​profile

​context — for signups that happen on your server

​Authentication, unusually

​Response

​hamla.track() — the browser door

​What an event does once stored

​Segment fields

​Names that move the journey stage

​What an event means

​What your ad accounts hear

​If you send nothing

​Traits and custom fields

​Limits

​Node SDK

The doors

Authentication

POST /api/sdk/track

Fields

`identity`

Response

Errors

POST /api/sdk/track/batch

What backfill deliberately does not do

Response

POST /api/sdk/identify

Fields

`profile`

`context` — for signups that happen on your server

Authentication, unusually

Response

hamla.track() — the browser door

What an event does once stored

Segment fields

Names that move the journey stage

What an event means

What your ad accounts hear

If you send nothing

Traits and custom fields

Limits

Node SDK