List Events

Retrieve a paginated list of custom events recorded for a contact in your workspace. The contact path parameter accepts either the contact UUID or the current workspace identity value.

Query Options

Searching, sorting, and pagination supported by the list endpoint

  • Use search to match event names.
  • Use sorting[] to control sort order. If you do not provide sorting, events are ordered by created_at.
  • Use per_page to control pagination size. The default is 10.
  • The resolved contact must belong to the API key's workspace.
GET
/v1/contacts/:contact/events

List custom events recorded for a contact

Path parameters

contactstring Required

Contact UUID or the current workspace identity value

Request body

searchstring

Query parameter used to search by event name

per_pagenumber

Query parameter for results per page. Defaults to `10`.

sorting[]array

Query parameter containing JSON-encoded sort descriptors

Request
List Events
curl "https://api.leadpush.io/v1/contacts/:contact/events?per_page=10" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}"
List Events by Identity
curl "https://api.leadpush.io/v1/contacts/person@example.com/events?per_page=10" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}"
Search Events
curl "https://api.leadpush.io/v1/contacts/:contact/events?search=signed_up&sorting[]=%7B%22id%22%3A%22created_at%22%2C%22desc%22%3Atrue%7D" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}"
Response Example
{
"data": [
  {
    "uuid": "<event_uuid>",
    "event_name": "contact.signed_up",
    "attributes": {
      "plan": "pro",
      "source": "api"
    },
    "created_at": "2021-01-01T00:00:00.000Z"
  }
],
"meta": {
  "current_page": 1,
  "per_page": 10,
  "total": 1,
  "last_page": 1,
  "has_next": false
}
}

Success and Errors

Expected outcomes for list event requests

  • Successful requests return a paginated event collection.
  • 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 token does not have access to the workspace.