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.
  • The resolved contact must belong to the API key's workspace.
  • If attributes is omitted, the event is recorded with an empty attribute payload.
POST
/v1/contacts/:contact/events

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

Path parameters

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

Request
Send Event by UUID
curl -X POST https://api.leadpush.io/v1/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/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 API key's workspace.
  • The endpoint returns 403 if the resolved contact does not belong to the API key's workspace 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.

Explore this topic

Related implementation resources

Continue from this endpoint or setup guide into the most relevant product workflows and operational guidance.

ProductEmail Segmentation & Audience BuilderBuild live audiences from profile data, product behavior, exclusions, and events as they happen.Knowledge baseBuild Audience SegmentsCreate reusable audiences from attributes, events, subscriptions, and message activity.Knowledge baseBuild Campaign FlowsConnect triggers, timing, decisions, and actions into an automated customer journey.Use caseOnboarding EmailsGuide customers toward activation with behavior-aware onboarding campaigns.