---
title: "Invoke a journey"
method: POST
path: "/journeys/{templateId}/invoke"
tags: ["Journeys"]
---

# Invoke a journey

`POST /journeys/{templateId}/invoke`

Starts a journey run for one user and returns a runId. Runs execute asynchronously, so the response arrives before any message is sent.

## Path parameters

- `templateId` string, required

## Headers

- `Idempotency-Key` string
- `x-idempotency-expiration` string

## Request body

- JourneysInvokeRequest — Request body for invoking a journey. Requires either a user identifier or a profile with contact information. User identifiers can be provided via user_id field, or resolved from profile/data objects (user_id, userId, or anonymousId fields).
  - `user_id` string — A unique identifier for the user. If not provided, the system will attempt to resolve the user identifier from profile or data objects.
  - `profile` object — Profile data for the user. Can contain contact information (email, phone_number), user identifiers (user_id, userId, anonymousId), or any custom profile fields. Profile fields are merged with any existing stored profile for the user. Include context.tenant_id to load a tenant-scoped profile for multi-tenant scenarios.
  - `data` object — Data payload passed to the journey. The expected shape can be predefined using the schema builder in the journey editor. This data is available in journey steps for condition evaluation and template variable interpolation. Can also contain user identifiers (user_id, userId, anonymousId) if not provided elsewhere.

## Response `202`

Journey invocation accepted

- JourneysInvokeResponse
  - `runId` string, required — A unique identifier for the journey run that was created.

## Other responses

- `400` — Bad Request - validation error, invalid version, or missing recipient
- `404` — Journey not found
- `422` — Unprocessable Entity - trigger conditions failed, template archived or disabled

---

[API](https://skmtc.net/trycourier/apis/courier.md) · [All operations](https://skmtc.net/trycourier/apis/courier/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trycourier/courier/versions/04f69fbf96a5/schema)