Skip to main content
Journeys are multi-step flows (wait, branch, send, repeat) that Spotzee runs in the background once a user enters them. Use this flow to enter a user into a journey from your backend the moment something happens in your product.

​
What you’ll build

A backend call that:
  1. Picks the right journey for the trigger event.
  2. Enters one user into it at a chosen entrance step.
  3. Passes per-entrance event data the journey’s conditions and templates can use.

​
Prerequisites

You’ll need a sk_ project key. The journey must already be authored in the Spotzee UI and set to status: "live". Only live journeys accept new entrances.

​
Walkthrough

1

Author and publish the journey

Build the journey in the Spotzee UI: entry condition, branches, sends, waits. Set its status to Live when you’re ready. Draft and Off journeys reject POST /journeys/{id}/trigger calls.
2

Find the journey ID and entrance step

GET /journeys?limit=100 returns every journey in the project. In production, hold a stable mapping in your config (e.g. WELCOME_JOURNEY_ID) rather than discovering it at runtime.Each journey has one or more entrance steps (the entry nodes in its graph). The trigger call must specify which one to enter the user at via the entrance_id field. This is a numeric step identifier from the journey’s published graph.
3

Trigger an entrance

The endpoint enters one user at a time. The body has three fields: entrance_id (which entrance step to use), user (the user identifier), and an optional event payload available to journey conditions and templates as {{event}}.
The user object requires external_id and accepts the standard user fields (email, phone, device_token, timezone, locale) plus any additional custom attributes. To enter many users, call this endpoint once per user (typically from a worker that fans out from your queue).
4

Handle the response

On success the response confirms the entrance was queued. If the user wasn’t found and the supplied user block didn’t carry enough information to upsert one, the call returns an error from the error catalogue.
5

Verify in the journey view

The journey’s runtime view in the Spotzee UI shows fresh entrances within seconds. For email messages sent by the journey, Enterprise high-deliverability projects can forward enabled delivery events from Settings → Webhook Endpoints.

​
Pitfalls to avoid

Don’t trigger the same user into the same journey twice for the same event. Most journeys aren’t designed to be entered concurrently. Use a deterministic Idempotency-Key (typically <journey>:<user>:<event-id>) so retries are safe. See Idempotency.
  • Don’t trigger a Draft journey. Spotzee returns 409 until the journey is set Live. Promote it in the UI first.
  • Don’t pack the event block with stale info. Conditions and templates downstream will reference whatever you pass at trigger time. If a step depends on event.trial_ends_at, set it correctly when you trigger.
  • Don’t fire triggers in a tight loop without pacing. Each call enters one user; if you’re entering thousands at once, fan out through a queue/worker that respects rate limits. See Rate limits.

​
Reference