Triggers

A trigger is a call you repeat. GET /api/v1/triggers/{event} returns the newest events of one type first. You need a key with the contacts:read scope.

The events

This list is built from the API’s own spec, so it has every event the API reports.

curl -s "https://app.contactz.app/api/v1/triggers/contact.created?limit=2" \
  -H "Authorization: Bearer $CZ_KEY"

{
  "items": [
    {
      "id": "d833e0b8-dd4e-4232-95ca-c53bb44a09ec",
      "event": "contact.created",
      "occurredAt": "2026-11-01T14:47:15.389252Z",
      "contactId": "772189b9-ef30-44a8-ace6-3955d061633c",
      "contact": { "displayName": "Ada Lovelace", "frozen": false }
    }
  ],
  "nextCursor": "…"
}

Polling

• Deduplicate by id. Polling again with nothing new returns the same ids. A new event appears at the top.
• Page back with cursor. When a page has nextCursor, pass it back as cursor to read older events. limit is 1 to 100, and 50 when you leave it out.
• Poll every 5 minutes or less often. See Rate limits.
• An unknown event name is a 404 not_found.

What an item carries

One trigger event. Which of the optional fields it carries depends on event: the contact events carry contactId and contact; a merge also carries absorbedContactIds and automatic; a review carries the pair , contactId, contact, pairedContactId, pairedContact , and confidence; an account event carries accountId, account and attention.

Each item carries what an automation needs, so you don’t need a second call. The contact’s fields are null when the contact has since been deleted or merged. Every contact in an item has the same fields as a read, including frozen.

Why an account needs attention

For account.needs_attention, the item’s attention is one of these: