Track Custom Event

Track a custom event for a contact, identified by either their email address or their phone number. Custom events can be used to trigger automations with the CUSTOM_EVENT trigger type.

---

Endpoint

POST https://api.campaignlark.com/v1/events

---

Request Body

Field	Type	Required	Description
email_address	string	required*	Email address of the contact to associate the event with.
phone_number	string	required*	Phone number of the contact to associate the event with. Normalized to E.164 before the lookup, and requires a workspace field with the phone_number merge tag.
event_name	string	required	Name of the custom event to track.
properties	object	optional	Arbitrary key-value map of event properties. Defaults to {} if omitted.

* Provide exactly one of email_address or phone_number.

---

Sample Request

POST https://api.campaignlark.com/v1/events
Content-Type: application/json

{
  "email_address": "joffrey@example.com",
  "event_name": "purchase_completed",
  "properties": {
    "order_id": "ORD-9001",
    "total": 99.99,
    "currency": "USD"
  }
}

The same event, tracked against a contact identified by phone number:

POST https://api.campaignlark.com/v1/events
Content-Type: application/json

{
  "phone_number": "+14155550123",
  "event_name": "purchase_completed",
  "properties": {
    "order_id": "ORD-9001"
  }
}

---

Success — 200 OK

{
  "data": {
    "queued": true
  }
}

---

Errors

Status	Message	Cause
400	Email address or phone number is required. Please provide the contact's email address or phone number.	Both email_address and phone_number are missing or empty.
400	Please provide an email address or phone number, not both.	Both email_address and phone_number were supplied.
400	Event name is required.	event_name field is missing or empty.
400	We couldn't find a contact with the phone number '<number>'.	No contact in the workspace has that phone number.
400	Phone number is invalid. Please provide a valid phone number.	The provided phone_number could not be parsed, or it has no country code and the phone_number field has no default region.
400	We couldn't find a PhoneNumber field in your workspace. Please check your workspace configuration and try again.	The workspace has no field with the phone_number merge tag.
429	(billing message)	Event usage limit for the workspace has been reached.

---

Properties Constraints

The properties object must adhere to the following limits:

Constraint	Limit
Top-level type	Must be a JSON object (not an array or primitive).
Serialized size	16 KB max.
Nesting depth	5 levels max (counting the top-level object as level 1).
Keys per object	50 max.
Key length	128 characters max.
Forbidden key characters	Keys cannot start with $ or contain ..