---
title: "Start a journey execution"
method: POST
path: "/journey_execution"
tags: ["Journey Execution"]
---

# Start a journey execution

`POST /journey_execution`

Trigger a journey execution for a contact via HTTP webhook

## Request body

- object
  - `journey_id` string, uuid, required — The journey ID to execute
  - `context` object, nullable — Context data for the journey execution, must match the schema defined in the journey trigger node
  - `contact` object, required — Contact details to import or find
    - `address_line1` string, nullable
    - `address_line2` string, nullable
    - `birthday` string, nullable
    - `campaign_messages_this_month` number
    - `city` string, nullable
    - `country` string, nullable
    - `created_at` string
    - `created_by` string, nullable
    - `created_by_api_token_id` string, nullable
    - `created_by_employee_id` string, nullable
    - `created_by_import_id` string, nullable
    - `deleted_at` string, nullable
    - `description` string, nullable
    - `display_name` string, nullable
    - `email` string, nullable
    - `email_health` 'healthy' | 'unhealthy' | 'unknown', nullable
    - `email_marketing_messages_this_month` number
    - `email_marketing_opt_in` boolean
    - `email_transactional_opt_in` 'legitimate_interest' | 'contract_fulfillment' | 'consent_granted', nullable
    - `external_id` string, nullable
    - `facebook` string, nullable
    - `facebook_health` 'healthy' | 'unhealthy' | 'unknown', nullable
    - `facebook_marketing_messages_this_month` number
    - `facebook_marketing_opt_in` boolean
    - `facebook_transactional_opt_in` 'legitimate_interest' | 'contract_fulfillment' | 'consent_granted', nullable
    - `fts` unknown
    - `full_name` string, nullable
    - `google_business_messaging` string, nullable
    - `google_business_messaging_health` 'healthy' | 'unhealthy' | 'unknown', nullable
    - `google_business_messaging_marketing_messages_this_month` number
    - `google_business_messaging_marketing_opt_in` boolean
    - `google_business_messaging_transactional_opt_in` 'legitimate_interest' | 'contract_fulfillment' | 'consent_granted', nullable
    - `id` string
    - `influenced_revenue` number
    - `instagram` string, nullable
    - `instagram_health` 'healthy' | 'unhealthy' | 'unknown', nullable
    - `instagram_marketing_messages_this_month` number
    - `instagram_marketing_opt_in` boolean
    - `instagram_transactional_opt_in` 'legitimate_interest' | 'contract_fulfillment' | 'consent_granted', nullable
    - `is_blocked` boolean
    - `last_external_review_rating` number, nullable
    - `last_interaction_at` string, nullable
    - `last_internal_review_rating` number, nullable
    - `last_outbound_at` string, nullable
    - `last_review_rating` number, nullable
    - `latest_marketing_opt_in_request_sent_at` string, nullable
    - `latest_review_request_message_sent_at` string, nullable
    - `marketing_opt_in` boolean, nullable
    - `number_of_marketing_opt_in_requests` number
    - `organisation_id` string
    - `postal` string, nullable
    - `postal_health` 'healthy' | 'unhealthy' | 'unknown', nullable
    - `postal_marketing_messages_this_month` number, nullable
    - `postal_marketing_opt_in` boolean
    - `postal_messages_this_month` number, nullable
    - `postal_transactional_opt_in` 'legitimate_interest' | 'contract_fulfillment' | 'consent_granted', nullable
    - `review_request_message_count` number
    - `salutation` string, nullable
    - `secondary_external_id` string, nullable
    - `sms` string, nullable
    - `sms_health` 'healthy' | 'unhealthy' | 'unknown', nullable
    - `sms_marketing_messages_this_month` number
    - `sms_marketing_opt_in` boolean
    - `sms_transactional_opt_in` 'legitimate_interest' | 'contract_fulfillment' | 'consent_granted', nullable
    - `transactional_opt_in` 'legitimate_interest' | 'contract_fulfillment' | 'consent_granted', nullable
    - `updated_at` string
    - `updated_by` string, nullable
    - `updated_by_api_token_id` string, nullable
    - `updated_by_employee_id` string, nullable
    - `updated_by_import_id` string, nullable
    - `whatsapp` string, nullable
    - `whatsapp_health` 'healthy' | 'unhealthy' | 'unknown', nullable
    - `whatsapp_marketing_messages_this_month` number
    - `whatsapp_marketing_opt_in` boolean
    - `whatsapp_transactional_opt_in` 'legitimate_interest' | 'contract_fulfillment' | 'consent_granted', nullable
    - `zipcode` string, nullable

## Response `202`

Journey execution started successfully

- object
  - `success` boolean, required
  - `journey_execution_id` string, uuid, required
  - `contact_id` string, uuid, required

## Other responses

- `400` — Invalid input or context validation failed
- `404` — Journey version or trigger node not found
- `409` — Journey execution already active for this contact
- `500` — Internal server error

## Changes

- **2026-08-14** `22a9b3b009d1` — 2 warning
  - removed the request property `contact/created_by_rule_id`
  - removed the request property `contact/updated_by_rule_id`

[Change history](https://skmtc.dev/getmateo/apis/mateo-api/changes/journey_execution/post.md)

---

[API](https://skmtc.dev/getmateo/apis/mateo-api.md) · [All operations](https://skmtc.dev/getmateo/apis/mateo-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getmateo/mateo-api/revisions/22a9b3b009d1/schema)