Track events from your app

Events drive segments, journeys and reports. Send them from your server with a secret key.

What you need first

• A key with events:write (and profiles:write to create people from events).

• A stable user id from your app, used as externalId.

1. Send an event

curl -s -X POST "$BASE/v1/events" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Signed up","occurredAt":"2026-10-20T09:00:00Z","dedupeKey":"signup-usr_grace",
       "properties":{"plan":"free","source":"landing"},
       "profile":{"email":"grace@example.com","externalId":"usr_grace","firstName":"Grace","lastName":"Hopper"},
       "context":{"utm":{"utm_source":"docs","utm_campaign":"quickstart"}}}'
# {"accepted":1,"duplicates":0,"rejected":[]}

• The person is created or updated from profile. Later events need only {"profile":{"externalId":"usr_grace"}}.

• dedupeKey makes retries safe. A repeat counts in duplicates and is not stored twice.

• context.utm fills the person's first and last touch.

2. Stitch an anonymous visitor

Send events with an anonymousId before sign-up, then identify:

curl -s -X POST "$BASE/v1/events" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Viewed pricing","anonymousId":"anon-123","dedupeKey":"pv-anon-123-1"}'

curl -s -X POST "$BASE/v1/identify" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"anonymousId":"anon-123","identifiers":{"email":"margaret@example.com"},"traits":{"company":"Apollo Guidance"}}'
# {"profileId":"...","created":true}

The earlier anonymous events now belong to that person. Set names with PATCH /v1/profiles/<id> {"firstName":"Margaret"}.

consent on identify is tracking consent (cookies), not permission to email.

3. Send many at once

curl -s -X POST "$BASE/v1/events/batch" \
  -H "Authorization: Bearer $HERMETICA_API_KEY" -H "Content-Type: application/json" \
  -d '{"events":[{"name":"Connected provider","profile":{"externalId":"usr_grace"},"properties":{"provider":"ses"},"dedupeKey":"cp-usr_grace-1"}]}'

One bad event is rejected by its index. The rest land.

4. Check what arrived

curl -s "$BASE/v1/metrics" -H "Authorization: Bearer $HERMETICA_API_KEY"

This lists every event name with counts. GET /v1/profiles/<id>/events shows one person's events.

From the browser

Browser and mobile SDKs use a publishable site key. Create it in the web app under Settings → Sites, or with POST /v1/sites and a secret key that has api_keys:write (see API keys). See SDKs.

Next: Build your first segment.