Journey Execution via HTTP - Hellomateo API Documentation

Hellomateo allows you to trigger journey executions via an HTTP API endpoint. This is useful when you want to start a journey for a contact based on external events, such as a purchase in, a form submission, or any other event that happens outside of Hellomateo.

Prerequisites

Before you can trigger a journey execution via HTTP, you need to:

Create a journey in Hellomateo with an HTTP Trigger node
Define a context schema in the HTTP trigger node (can be empty if no context is needed)
Publish the journey

Context Schema

The HTTP trigger node allows you to define a context schema that specifies what data must be provided when triggering the journey. This is useful when you want to pass additional information about the event that triggered the journey, such as order details, product information, or any other data that you want to use in the journey. For example, if you want to trigger a journey when a customer makes a purchase, you might define a context schema like this:

{
  "order_id": {
    "type": "string",
    "display_name": "Order ID"
  },
  "product_name": {
    "type": "string",
    "display_name": "Product Name"
  },
  "total_amount": {
    "type": "string",
    "display_name": "Total Amount"
  }
}

All fields defined in the schema are required and must be non-empty strings. If you don’t need any context data, you can define an empty schema {}.

Triggering a Journey

To trigger a journey execution, make a POST request to the /journey_execution endpoint:

curl "https://integration.getmateo.com/api/v1/journey_execution" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "journey_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "context": {
      "order_id": "ORD-12345",
      "product_name": "Premium Package",
      "total_amount": "99.99"
    },
    "contact": {
      "email": "customer@example.com",
      "full_name": "Jane Doe",
      "external_id": "ERP-123"
    }
  }'

The context field must match the schema defined in the HTTP trigger node (use {} for empty schemas). The contact field uses the same import mechanism as the Contact Import - it will update existing contacts or create new ones based on unique identifiers like email, whatsapp, sms, or external_id.

Successful Response

If the journey execution was triggered successfully, you will receive a 202 Accepted response with the following payload:

{
  "success": true,
  "journey_execution_id": "7f3e9b1a-4d2c-4e6f-8a9b-1c2d3e4f5g6h",
  "contact_id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7g8h9i0j"
}

You can use the journey_execution_id to track the execution status via the Hellomateo Web App. The contact_id can be used to query or update the contact via the Contact API.

Error Handling

The endpoint performs validation before starting the journey execution. If validation fails, you will receive an appropriate error response:

400 Bad Request - Context Validation Failed

If the provided context does not match the schema defined in the HTTP trigger node:

{
  "code": "VALIDATION_ERROR",
  "message": "Validation error: Required at \"product_name\"; Required at \"total_amount\"",
  "statusCode": 400
}

400 Bad Request - Missing Context Schema

If the HTTP trigger node has no context schema defined:

{
  "code": "MISSING_CONTEXT_SCHEMA",
  "message": "HTTP trigger must have a context schema defined",
  "statusCode": 400
}

404 Not Found - Journey Not Found

If the journey does not exist or is not published:

{
  "code": "JOURNEY_VERSION_NOT_FOUND",
  "message": "Journey version not found",
  "statusCode": 404
}

404 Not Found - No HTTP Trigger

If the journey does not have an HTTP trigger node:

{
  "code": "TRIGGER_NODE_NOT_FOUND",
  "message": "HTTP trigger node not found",
  "statusCode": 404
}

409 Conflict - Journey Already Active

If the journey does not allow concurrent executions and there is already an active execution for the contact:

{
  "message": "Journey execution already active for this contact",
  "contact_id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7g8h9i0j",
  "journey_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Discovering HTTP Trigger Journeys via API

You can use the Hellomateo API to discover available journeys and their HTTP trigger nodes programmatically. This is useful for building dynamic integrations or listing available journeys in your application.

Finding HTTP Trigger Journeys in a Single Request

Using PostgREST query syntax, you can retrieve all published journey versions with their HTTP trigger nodes and required context schemas in a single API call:

curl "https://integration.getmateo.com/api/v1/journey_version?select=id,published,version,journey!inner(id,name,key),journey_node!inner(id,event_type,extra_context_schema,name)&published=eq.true&order=version.desc&journey_node.event_type=eq.http" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

This query:

Queries journey_version table and filters for published=true
Orders by version descending to get latest versions first
Joins with journey (inner join to get journey details)
Joins with journey_node and filters for event_type=http
Returns journey version details with journey info and HTTP trigger node’s extra_context_schema

Example Response

[
  {
    "id": "4d1e4d4e-1e5f-4e7f-9b1c-2d3e4f5g6h7i",
    "published": true,
    "version": 3,
    "journey": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "Order Confirmation Journey",
      "key": "order-confirmation"
    },
    "journey_node": [
      {
        "id": "5e2f5e5f-2f6g-5f8g-0c2d-3e4f5g6h7i8j",
        "event_type": "http",
        "name": "HTTP Trigger",
        "extra_context_schema": {
          "order_id": {
            "type": "string",
            "display_name": "Order ID"
          },
          "total_amount": {
            "type": "string",
            "display_name": "Total Amount"
          }
        }
      }
    ]
  }
]

Querying Individual Tables

You can also query the tables separately for more flexibility:

List All Journeys

curl "https://integration.getmateo.com/api/v1/journey" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Published Journey Versions

curl "https://integration.getmateo.com/api/v1/journey_version?published=eq.true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Find HTTP Trigger Nodes

curl "https://integration.getmateo.com/api/v1/journey_node?event_type=eq.http&type=eq.trigger" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Available Fields

The following fields are available for each table: journey:

id - Journey ID
name - Journey name
key - Journey key (optional)
status - Journey status (draft, active, archived)
organisation_id - Organisation ID

journey_version:

id - Version ID
journey_id - Journey ID
published - Whether this version is published
version - Version number
organisation_id - Organisation ID

journey_node:

id - Node ID
journey_version_id - Journey version ID
type - Node type (trigger, action, etc.)
event_type - Event type for trigger nodes (http, manual, etc.)
extra_context_schema - Schema for context data required by HTTP triggers
name - Node name (optional)
organisation_id - Organisation ID

Using Context Data in Your Journey

Once a journey execution is triggered with context data, you can access the context fields in any node within the journey using the expression editor. This allows you to personalize messages, create conditional branches, or use the context data in any other way within your journey.

Examples

Updating an Existing Contact

{
  "journey_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "context": {
    "order_id": "ORD-12345"
  },
  "contact": {
    "external_id": "ERP-123",
    "full_name": "Jane Doe Updated",
    "my_custom_field": "new_value"
  }
}

Creating a New Contact

{
  "journey_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "context": {},
  "contact": {
    "email": "newcustomer@example.com",
    "full_name": "John Smith",
    "whatsapp": "+1234567890"
  }
}

Best Practices

Use External IDs: Use external_id to link contacts between your system and Hellomateo for easier synchronization
Keep Schemas Simple: Only include context fields you actually need in the journey
Handle Errors: Implement proper error handling for all possible response codes
Async Processing: The 202 response means the execution is queued, not completed
Publish Before Triggering: Only published journeys can be triggered via the API

Recipes

​Prerequisites

​Context Schema

​Triggering a Journey

​Successful Response

​Error Handling

​400 Bad Request - Context Validation Failed

​400 Bad Request - Missing Context Schema

​404 Not Found - Journey Not Found

​404 Not Found - No HTTP Trigger

​409 Conflict - Journey Already Active

​Discovering HTTP Trigger Journeys via API

​Finding HTTP Trigger Journeys in a Single Request

​Example Response

​Querying Individual Tables

​List All Journeys

​Get Published Journey Versions

​Find HTTP Trigger Nodes

​Available Fields

​Using Context Data in Your Journey

​Examples

​Updating an Existing Contact

​Creating a New Contact

​Best Practices