> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke a journey

> Invoke a journey by id or alias to start a new run. The response includes a `runId` identifying the run.



## OpenAPI

````yaml /openapi-specs/openapi.documented.yml post /journeys/{templateId}/invoke
openapi: 3.0.1
info:
  title: Courier
  description: The Courier REST API.
  version: 0.0.1
servers:
  - url: https://api.courier.com
    description: Production
security: []
paths:
  /journeys/{templateId}/invoke:
    post:
      tags:
        - Journeys
      summary: Invoke a journey
      description: >-
        Invoke a journey by id or alias to start a new run. The response
        includes a `runId` identifying the run.
      operationId: journeys_invoke
      parameters:
        - name: templateId
          in: path
          description: >-
            A unique identifier representing the journey to be invoked. Accepts
            a Journey ID or Journey Alias.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JourneysInvokeRequest'
            examples:
              WithUserId:
                summary: Invoke with user_id
                value:
                  user_id: user-123
                  data:
                    order_id: order-456
                    amount: 99.99
              WithProfile:
                summary: Invoke with profile containing contact info
                value:
                  profile:
                    email: user@example.com
                    first_name: John
                  data:
                    welcome_message: Hello!
              WithUserIdInProfile:
                summary: Invoke with user_id in profile
                value:
                  profile:
                    user_id: user-123
                    email: user@example.com
                  data:
                    foo: bar
              WithTenantScopedProfile:
                summary: Invoke with tenant-scoped profile
                description: Load a user's profile scoped to a specific tenant
                value:
                  user_id: doctor-smith
                  profile:
                    context:
                      tenant_id: hospital-a
                  data:
                    report_date: '2024-01-15'
      responses:
        '202':
          description: Journey invocation accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JourneysInvokeResponse'
              examples:
                Example1:
                  value:
                    runId: 1-65f240a0-47a6a120c8374de9bcf9f22c
        '400':
          description: >-
            Bad Request - validation error, invalid version, or missing
            recipient
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                MissingTemplateId:
                  value:
                    type: invalid_request_error
                    message: templateId is required
                MissingRecipient:
                  value:
                    type: invalid_request_error
                    message: >-
                      User identifier or profile required. Provide user_id,
                      user_id/userId/anonymousId in profile/data, or profile
                      with contact info.
                InvalidVersion:
                  value:
                    type: invalid_request_error
                    message: >-
                      Invalid automation version. Expected 2025-09-03, got
                      2022-12-01
        '404':
          description: Journey not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
              examples:
                TemplateNotFound:
                  value:
                    type: invalid_request_error
                    message: Automation template abc-123 not found
        '422':
          description: >-
            Unprocessable Entity - trigger conditions failed, template archived
            or disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity'
              examples:
                TriggerConditionFailed:
                  value:
                    type: invalid_request_error
                    message: Trigger conditions not met
                ArchivedTemplate:
                  value:
                    type: invalid_request_error
                    message: Cannot invoke archived automation template abc-123
                DisabledTemplate:
                  value:
                    type: invalid_request_error
                    message: Cannot invoke disabled automation template abc-123
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Courier from '@trycourier/courier';


            const client = new Courier({
              apiKey: process.env['COURIER_API_KEY'], // This is the default and can be omitted
            });


            const journeysInvokeResponse = await
            client.journeys.invoke('templateId', {
              data: { order_id: 'order-456', amount: 99.99 },
              user_id: 'user-123',
            });


            console.log(journeysInvokeResponse.runId);
        - lang: Python
          source: |-
            import os
            from courier import Courier

            client = Courier(
                api_key=os.environ.get("COURIER_API_KEY"),  # This is the default and can be omitted
            )
            journeys_invoke_response = client.journeys.invoke(
                template_id="templateId",
                data={
                    "order_id": "order-456",
                    "amount": 99.99,
                },
                user_id="user-123",
            )
            print(journeys_invoke_response.run_id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/trycourier/courier-go\"\n\t\"github.com/trycourier/courier-go/option\"\n)\n\nfunc main() {\n\tclient := courier.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tjourneysInvokeResponse, err := client.Journeys.Invoke(\n\t\tcontext.TODO(),\n\t\t\"templateId\",\n\t\tcourier.JourneyInvokeParams{\n\t\t\tJourneysInvokeRequest: courier.JourneysInvokeRequestParam{},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", journeysInvokeResponse.RunID)\n}\n"
        - lang: Java
          source: |-
            package com.courier.example;

            import com.courier.client.CourierClient;
            import com.courier.client.okhttp.CourierOkHttpClient;
            import com.courier.models.journeys.JourneyInvokeParams;
            import com.courier.models.journeys.JourneysInvokeRequest;
            import com.courier.models.journeys.JourneysInvokeResponse;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    CourierClient client = CourierOkHttpClient.fromEnv();

                    JourneyInvokeParams params = JourneyInvokeParams.builder()
                        .templateId("templateId")
                        .journeysInvokeRequest(JourneysInvokeRequest.builder().build())
                        .build();
                    JourneysInvokeResponse journeysInvokeResponse = client.journeys().invoke(params);
                }
            }
        - lang: Ruby
          source: |-
            require "courier"

            courier = Courier::Client.new(api_key: "My API Key")

            journeys_invoke_response = courier.journeys.invoke("templateId")

            puts(journeys_invoke_response)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Courier\Client;

            use Courier\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('COURIER_API_KEY') ?: 'My API
            Key');


            try {
              $journeysInvokeResponse = $client->journeys->invoke(
                'templateId',
                data: ['order_id' => 'bar', 'amount' => 'bar'],
                profile: ['foo' => 'bar'],
                userID: 'user-123',
              );

              var_dump($journeysInvokeResponse);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: >-
            using System;

            using Courier;

            using Courier.Models.Journeys;


            CourierClient client = new();


            JourneyInvokeParams parameters = new() { TemplateID = "templateId"
            };


            var journeysInvokeResponse = await
            client.Journeys.Invoke(parameters);


            Console.WriteLine(journeysInvokeResponse);
        - lang: CLI
          source: |-
            courier journeys invoke \
              --api-key 'My API Key' \
              --template-id templateId
components:
  schemas:
    JourneysInvokeRequest:
      title: JourneysInvokeRequest
      type: object
      description: >-
        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).
      properties:
        user_id:
          type: string
          description: >-
            A unique identifier for the user. If not provided, the system will
            attempt to resolve the user identifier from profile or data objects.
        profile:
          type: object
          additionalProperties: true
          description: >-
            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:
          type: object
          additionalProperties: true
          description: >-
            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.
    JourneysInvokeResponse:
      title: JourneysInvokeResponse
      type: object
      properties:
        runId:
          type: string
          description: A unique identifier for the journey run that was created.
      required:
        - runId
    BadRequest:
      title: BadRequest
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/BaseError'
    NotFound:
      title: NotFound
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/BaseError'
    UnprocessableEntity:
      title: UnprocessableEntity
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/BaseError'
    BaseError:
      title: BaseError
      type: object
      properties:
        message:
          type: string
          description: A message describing the error that occurred.
      required:
        - message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````