PRprivy
Contacts

List a contact's activity

Changed on

Retrieve the contact's activity timeline — signups, email and SMS sends, opens and clicks, orders, checkouts, tag changes — newest first. This is the same record the Privy dashboard's contact page shows, so "why did this contact get X?" can be answered from the API alone: find the send, the signup that triggered it, and the display or campaign each traces to.

Each entry names its type (the event vocabulary below, as stored), when it happened, the display or campaign it belongs to (when the event carries one, even one since deleted), and the event's raw properties, whose shape varies by type (the recipient IP and user agent recorded on email opens and clicks, and the IP-derived location on signups, are not included).

By default the timeline covers the last 24 months; narrow it with occurred_after / occurred_before (both bounds exclusive; a bare date means midnight at the start of that day) or to one event type with type.

Required scope: contacts_read

get/contacts/{id}/events

Request

  • Base URL
    https://api.privy.com/v1
  • Auth
    HTTP bearer

Path parameters

idstring required

The contact's unique identifier (returned as id in contact responses). Ids are opaque cus_-prefixed strings — a numeric id from a Privy dashboard URL is not a valid API id and will 404; list contacts, or look the contact up by ?email= or ?phone_number=, instead.

Query parameters

typestring

Only return events of this type. Any type value a row carries is accepted (including names a merchant's own integration sent through the events ingest), so a type read off the timeline always filters. Common values: customer-subscribed, email-sent, email-delivered, email-opened, email-clicked, text-message-sent, text-message-delivered, view, new-session, redemption, signup, sms-signup, order-created, checkout-started, customer-tag-added, customer-tag-removed.

occurred_afterstring

Only events after this instant (exclusive). ISO 8601 datetime or date. Defaults to 24 months before occurred_before — 24 months ago when neither bound is given.

occurred_beforestring

Only events before this instant (exclusive). ISO 8601 datetime or date. Defaults to now.

pageinteger

Page number (starts at 1).

per_pageinteger

Number of results per page. Values outside 10–100 are clamped to the nearest bound.

Headers

Privy-Account-Idstring

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

Response

A paginated list of the contact's events, newest first.

notestring

Present only when the account's plan limits the timeline to signup events.

Example response

{
  "data": [
    {
      "type": "email-opened",
      "occurred_at": "2026-08-20T14:22:00Z",
      "campaign": {
        "id": "gk2P8Zw1Lq",
        "title": "Welcome Popup",
        "type": "display"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 142,
    "total_pages": 6
  }
}

Changes

  • cf0885e90d5aRevision changes
    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

  • fe500ab59b3bRevision changes
    • info

      endpoint added