Custom Entity Journeys

Custom entities attach schema-validated data from systems such as ERPs, ticketing platforms, and voucher services to a contact. A journey can start when an entity for a specific definition is created or when its data changes.

Before you begin, create an API token and identify the contact that should own the custom entity.

Create a custom entity definition

A definition gives the entity type a stable key and defines the JSON Schema used to validate its data.

curl https://api.getmateo.com/v1/custom-entity-definitions \
  --request POST \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01" \
  --header "Content-Type: application/json" \
  --data '{
    "key": "voucher",
    "name": "Voucher",
    "schema": {
      "type": "object",
      "properties": {
        "voucher_id": { "type": "string" },
        "status": { "type": "string" },
        "code": { "type": "string" }
      },
      "required": ["voucher_id", "status", "code"]
    }
  }'

The response includes the definition id, its key, and the schema. Prefer the key in integrations when it is stable across your environments. See Create Custom Entity Definition for the complete request and response schemas.

Configure the journey

In hellomateo:

1. Add a Custom Entity trigger to a journey.
2. Select the custom entity definition.
3. Choose whether the journey starts when an entity is created or changed.
4. Publish and activate the journey.

Journey trigger configuration and discovery are managed in hellomateo and are not exposed by the public API.

Create a custom entity

Create an entity for a contact to start journeys configured with the created trigger for the voucher definition:

curl https://api.getmateo.com/v1/custom-entities \
  --request POST \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01" \
  --header "Content-Type: application/json" \
  --data '{
    "custom_entity_definition_key": "voucher",
    "contact_id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
    "external_id": "VOUCH-12345",
    "data": {
      "voucher_id": "VOUCH-12345",
      "status": "sent",
      "code": "102938405"
    }
  }'

Provide exactly one of custom_entity_definition_key and custom_entity_definition_id. The API validates data against the selected definition and returns the created entity with 201 Created.

external_id identifies the entity in your system and supports later lookups. It does not make POST /v1/custom-entities an upsert. If a create request has an ambiguous result, look up the entity before retrying instead of assuming the request failed.

Update a custom entity

Use the definition key and external ID to update an entity without storing its hellomateo ID:

curl "https://api.getmateo.com/v1/custom-entities/by?custom_entity_definition_key=voucher&external_id=VOUCH-12345" \
  --request PATCH \
  --header "Authorization: Bearer $MATEO_API_TOKEN" \
  --header "hellomateo-version: 2026-07-01" \
  --header "Content-Type: application/json" \
  --data '{
    "data": {
      "voucher_id": "VOUCH-12345",
      "status": "used",
      "code": "102938405"
    }
  }'

Journeys configured with the changed trigger start only when the entity's data value actually changes. Updating other supported fields without changing data, or sending the existing data again, does not start that journey.

See Update Custom Entity By Locator for all locator and body fields.

Recommended practices

• Use one definition for each domain object, such as vouchers, tickets, or subscriptions.
• Keep schemas focused on fields used by your journeys and integrations.
• Use an external ID that is unique within the definition, then update through the locator route.
• Test created and changed triggers before sending production data.