Send Event

Record a custom event for a contact in your workspace. The contact path parameter accepts either the contact UUID or the current workspace identity value.

Lookup Behavior

How the `contact` path parameter is resolved

  • Pass the contact UUID to send an event directly to a contact by its identifier.
  • Pass the workspace identity value to resolve the matching contact by email, phone, or your configured custom identity field.
  • Email identity lookups are normalized before matching, so surrounding whitespace and letter casing do not affect the result.
  • The resolved contact must belong to the workspace in the path.
  • If attributes is omitted, the event is recorded with an empty attribute payload.
POST
/v1/workspaces/:workspace/contacts/:contact/events

Record a custom event for a contact by UUID or identity value

Path parameters

workspacestring Required

ID of your workspace

contactstring Required

Contact UUID or the current workspace identity value

Request body

event_namestring Required

Event name to record for the contact, such as `contact.signed_up`

attributesobject

Optional JSON object payload stored with the event

Send Event by UUID
curl -X POST https://api.leadpush.io/v1/workspaces/:workspace/contacts/:contact/events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
  "event_name": "contact.signed_up",
  "attributes": {
    "plan": "pro",
    "source": "api"
  }
}'
Send Event by Identity
curl -X POST https://api.leadpush.io/v1/workspaces/:workspace/contacts/person@example.com/events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
  "event_name": "contact.opened"
}'

Success and Errors

Expected outcomes for event requests

  • Successful requests return an empty success response body.
  • The endpoint returns 404 if the contact path parameter does not resolve to a contact in the workspace.
  • The endpoint returns 403 if the resolved contact does not belong to the workspace in the path or the token does not have access to it.
  • The endpoint returns 422 if event_name is missing or attributes is not a JSON object payload.