Skip to main content
Custom entities are schema-driven data objects attached to contacts. They allow you to sync structured data from external systems (e.g. vouchers, tickets, subscriptions) into Hellomateo and automatically trigger journeys when that data is created or updated.

​
Prerequisites

Before you can trigger journeys with custom entities, you need to:
  1. Create a journey in Hellomateo with a Custom Entity trigger node
  2. Set the trigger’s event_type to custom_entity_created or custom_entity_changed
  3. Set the custom_entity_definition_id on the trigger node to scope it to a specific entity type
  4. Publish the journey and set it to active

​
Create a Custom Entity Definition

A custom entity definition describes the shape of your data. Create one via the API: 
curl "https://integration.getmateo.com/api/v1/custom_entity_definition" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Prefer: return=representation" \
  -d '{
    "key": "voucher",
    "name": "Voucher",
    "schema": {
      "type": "object",
      "properties": {
        "voucher_id": { "type": "string" },
        "status": { "type": "string" },
        "code": { "type": "number" }
      },
      "required": ["voucher_id", "status"]
    }
  }'
The key is a unique, human-readable identifier for the definition. The schema field accepts a JSON Schema that validates entity data on write.

​
Create a Custom Entity

Creating a custom entity triggers any journey with a custom_entity_created trigger scoped to the matching definition: 
curl "https://integration.getmateo.com/api/v1/custom_entity" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Prefer: return=representation" \
  -d '{
    "custom_entity_definition_key": "voucher",
    "contact_id": "CONTACT_UUID",
    "external_id": "VOUCH-12345",
    "data": {
      "voucher_id": "VOUCH-12345",
      "status": "sent",
      "code": 102938405
    }
  }'
FieldTypeRequiredDescription
custom_entity_definition_keystringYes*Key of the definition. Alternative to custom_entity_definition_id
custom_entity_definition_idUUIDYes*ID of the definition. Alternative to custom_entity_definition_key
contact_idUUIDYesThe contact this entity belongs to
external_idstringNoYour external system’s ID for this entity (enables upsert behavior)
dataobjectYesThe entity payload, validated against the definition’s schema
*Provide either custom_entity_definition_key or custom_entity_definition_id.

​
Update a Custom Entity

Updating a custom entity’s data field triggers any journey with a custom_entity_changed trigger scoped to the matching definition. The journey is only triggered when the data field actually changes: 
curl "https://integration.getmateo.com/api/v1/custom_entity?external_id=eq.VOUCH-12345&custom_entity_definition_key=eq.voucher" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Prefer: return=representation" \
  -d '{
    "data": {
      "voucher_id": "VOUCH-12345",
      "status": "used",
      "code": 120939485932
    }
  }'

​
Discovering Custom Entity Journeys

You can query the API to find journeys that have custom entity triggers: 
curl "https://integration.getmateo.com/api/v1/journey?select=id,name,status,latest_published_version:latest_published_version_id(id,version,journey_node!inner(id,event_type,custom_entity_definition_id))&latest_published_version.journey_node.event_type=in.(custom_entity_created,custom_entity_changed)" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
This returns all journeys with custom entity triggers, including their custom_entity_definition_id so you know which entity types they respond to.

​
Examples

​
Voucher Campaigns

Sync voucher codes from your marketing platform. Use custom_entity_created to send the voucher to the contact, and custom_entity_changed to trigger a follow-up when the voucher is redeemed.

​
ERP Sync

Sync contract or invoice data from your ERP. Trigger a journey when a new contract is created to kick off an onboarding flow.

​
Form Submissions

Store structured form submission data as custom entities. Use custom_entity_created to trigger a follow-up journey that sends a confirmation and assigns the contact to a sales rep.

​
Best Practices

  • Use external_id for idempotency: Set external_id to your system’s unique identifier (e.g. voucher code) so you can update entities by filtering on it
  • Prefer custom_entity_definition_key over UUID: Keys are human-readable and stable across environments
  • Keep schemas simple: Only include fields you need in the journey. Complex nested schemas are supported but harder to work with in the expression editor
  • One definition per domain object: Create separate definitions for orders, tickets, subscriptions, etc. rather than a generic one
  • Test with custom_entity_created first: It’s easier to verify since it fires on every insert, while custom_entity_changed only fires when data actually changes