Track custom events

​

What it is

​

Before you begin

• Choose a stable event name that will not change with display copy.
• Identify the contact associated with each event.
• Define the event properties and their data types.
• Decide which system timestamp represents when the activity occurred.

​

How it works

1. Create an event definition.
2. Add or update property definitions as the schema evolves.
3. Send event occurrences using the exact definition name.
4. Associate each occurrence with a contact ID, phone number, or Meta username.
5. Monitor rejected events and schema mismatches.

​

Request

​

Create an event definition

curl --request POST https://api.ycloud.com/v2/event/definitions \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "order_completed",
    "label": "Order completed",
    "description": "A customer completed an order.",
    "objectType": "CONTACT",
    "properties": [
      {
        "name": "order_value",
        "label": "Order value",
        "type": "NUMBER"
      }
    ]
  }'

​

Choose a contact identifier

​

Send an event by phone number

curl --request POST https://api.ycloud.com/v2/event/events \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventName": "order_completed",
    "occurTime": "2026-07-16T12:00:00.000Z",
    "contactPhoneNumber": "+16315551111",
    "properties": {
      "order_value": 99.9
    }
  }'

​

Send an event by username

curl --request POST https://api.ycloud.com/v2/event/events \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventName": "order_completed",
    "occurTime": "2026-07-16T12:00:00.000Z",
    "contactUsername": "customer_demo",
    "properties": {
      "order_value": 99.9
    }
  }'

​

Response

{
  "name": "order_completed",
  "label": "Order completed",
  "objectType": "CONTACT",
  "properties": [
    {
      "name": "order_value",
      "label": "Order value",
      "type": "NUMBER"
    }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{}

​

Schema evolution

• Add new optional properties when possible.
• Do not reuse an existing property name for a different meaning.
• Validate types before sending events.
• Keep event names and property names stable across environments.
• Version the event name when a breaking semantic change is unavoidable.

​

Limits and troubleshooting

• The event definition must exist before an occurrence is sent.
• Property names and values must match the definition.
• Use RFC 3339 for occurTime.
• Ensure the contact identifier resolves to the intended customer in your account.
• For contactUsername, check that the contact already exists and that the username matches the saved value without a leading @.
• Omit identifiers you do not want YCloud to use. A supplied phone number takes precedence over a username.
• A 200 response confirms acceptance, not that a downstream automation completed.