Skip to main content

Journeys API

Overview​

A journey is an automation workflow that reacts to an event or a schedule and then walks a subscriber through a sequence of steps — sending an email, waiting, branching on a condition, updating the subscriber, calling a webhook, or exiting. Journeys are referenced conceptually elsewhere in the DXP (e.g. the Forms trigger_journey post-submit action), but this page is the API reference for the resource that owns journey definitions and execution.

Authentication​

All endpoints require API key authentication:

X-API-Key: your-api-key-here

Journey structure​

A journey has a trigger (what starts it) and an ordered array of steps (what happens once started).

Triggers​

Trigger typeConfigNotes
event{ source: "email", type: "..." }type is a SparkPost email event. Values: bounce, delivery, injection, spam_complaint, out_of_band, policy_rejection, delay, click, open, initial_open, amp_click, amp_open, amp_initial_open, generation_failure, generation_rejection, list_unsubscribe, link_unsubscribe, unsubscribed, success, error.
event{ source: "website", type: "..." }type is a website event. Values: _first_open, _app_start, _app_end, _profile_set, _clickstream_error, _session_start, _user_engagement, _page_view, _click, _search, _scroll, _page_load.
time{ delay: { value, unit: "minutes" | "hours" | "days" } }Starts after a fixed delay.

Every trigger may also carry an optional condition expression that must evaluate to true for the trigger to fire.

Steps​

Step typeShapeNotes
action{ id, type: "action", action: {...}, next? }action.type is send_email (with { templateId, transactional } config), or one of update_subscriber | webhook | exit_journey.
wait{ id, type: "wait", wait: { duration: { value, unit } }, next }Pauses the journey. duration.value must be greater than 0.
condition{ id, type: "condition", condition: { if, then, else } }Branches to the step ID in then or else based on evaluating if.

Each step has a unique id; next (or then/else) points to the ID of the following step.

Create a journey​

POST /api/journeys

Request body​

{
  "name": "Welcome new subscribers",
  "description": "Send a welcome email after a new sign-up form submission triggers this journey.",
  "trigger": {
    "type": "time",
    "config": { "delay": { "value": 5, "unit": "minutes" } }
  },
  "steps": [
    {
      "id": "send_welcome",
      "type": "action",
      "action": {
        "type": "send_email",
        "config": { "templateId": "tmpl_welcome_01", "transactional": false }
      },
      "next": "wait_a_day"
    },
    {
      "id": "wait_a_day",
      "type": "wait",
      "wait": { "duration": { "value": 1, "unit": "days" } },
      "next": "exit"
    },
    {
      "id": "exit",
      "type": "action",
      "action": { "type": "exit_journey" }
    }
  ]
}

Example response​

{ "id": "jny_9kL3mP5n" }

List / search journeys​

GET /api/journeys

Optional query parameters page and limit.

Example response​

{
  "results": [
    {
      "version": 1,
      "created_at": "2026-01-01T00:00:00.123Z",
      "id": "jny_9kL3mP5n",
      "name": "Welcome new subscribers",
      "trigger": { "type": "time", "config": { "delay": { "value": 5, "unit": "minutes" } } },
      "status": "active",
      "stepsCount": 3
    }
  ],
  "total": 1,
  "totalPages": 1
}

status is one of draft, active, paused, archived.

Get journey configuration reference data​

GET /api/journeys/settings

Returns the reference lists used to build a journey in a builder UI: available event_sources, email_event_types, website_event_types, step_types, action_types, and wait_units.

Example response​

{
  "event_sources": ["email", "website"],
  "email_event_types": ["bounce", "delivery", "open", "click", "unsubscribed"],
  "website_event_types": ["_page_view", "_click", "_scroll"],
  "step_types": ["action", "wait", "condition"],
  "action_types": ["send_email", "update_subscriber", "webhook", "exit_journey"],
  "wait_units": ["minutes", "hours", "days"]
}

Get a journey by ID​

GET /api/journeys/{id}

Returns the full journey definition, including steps and jsonSchemaValidator (an optional JSON Schema used for additional validation), in addition to the list fields above.

Update a journey​

PUT /api/journeys/{id}

Body accepts the same shape as create, plus status (required on update).

Example response​

{ "id": "jny_9kL3mP5n" }

Delete a journey​

DELETE /api/journeys/{id}

Example response​

{ "id": "jny_9kL3mP5n" }

Start a journey instance​

POST /api/journeys/user-journey/start

Enrolls a subscriber into a running journey instance for an event trigger, outside the normal automatic trigger flow.

Request body​

{
  "type": "event",
  "config": { "source": "website", "type": "_page_view" },
  "subscriberId": "sub_9kL3mP5n",
  "data": { "page_url": "/pricing" }
}

Continue a journey instance​

POST /api/journeys/user-journey/continue

Advances an already-running journey instance to its next step.

Request body​

{ "id": "run_9kL3mP5n" }
note

The response shapes for start and continue are not fully specified in the OpenAPI contract beyond 200 OK — treat the response body as opaque and rely on subsequent GET /api/journeys/{id} / subscriber engagement data to observe effects.

  • Forms API — the trigger_journey post-submit action enrolls a form respondent into a journey.
  • Marketing Events API — the underlying email/website event stream journeys can trigger from.