Skip to main content
Track a named event for a contact. If the contact does not exist, it is created automatically. Matching workflows are triggered immediately after the event is recorded.
This endpoint accepts both public keys (pk_*) and secret keys (sk_*). Use a public key for client-side tracking (browser, mobile) and a secret key for server-side calls.

​
POST /v1/track

​
email
string
required
The contact’s email address. If no contact with this email exists in the project, a new one is created.
​
event
string
required
Event name, e.g. signed_up, purchased, plan_upgraded. Must not be a reserved system event name.
The following event name patterns are reserved and cannot be tracked manually:
  • email.* — e.g. email.sent, email.delivery, email.open, email.click, email.bounce, email.complaint, email.received
  • contact.subscribed, contact.unsubscribed
  • segment.<slug>.entry, segment.<slug>.exit
​
subscribed
boolean
default:"true"
Sets the contact’s subscription status. For new contacts this defaults to true. For existing contacts the value is only updated when this field is explicitly provided; omitting it preserves the current subscription state.
​
data
object
Custom data associated with the event and contact. Simple values are saved to the contact record (persistent). Use the non-persistent format for values that should only be available within workflows triggered by this event.

​
Response

​
success
boolean
required
true when the event was tracked successfully.
​
data
object
required

​
Examples

curl --request POST \
  --url https://next-api.useplunk.com/v1/track \
  --header 'Authorization: Bearer pk_live_yourpublickey' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "event": "signed_up"
  }'

​
Example response

200
{
  "success": true,
  "data": {
    "contact": "clx_contact_abc123",
    "event": "clx_event_xyz789",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us