The Contacts Activity API gives you a time-ordered feed of every change to your contacts — creations, role changes, permanent deletions, and merges. Unlike a standard contact list, it captures changes that would otherwise be invisible, making it easy to keep external tools like CRMs, data warehouses, and marketing platforms in sync.
Important: This endpoint requires the Preview API version and a token with the `read_users_companies` scope. Include the header `Intercom-Version: Preview` in every request.
Contact events tracked by the API
The feed records the following contact lifecycle events:
Contact created
Contact role changed
Contact permanently deleted
Contacts merged
This is especially useful if you sync contact data to external tools — CRMs, data warehouses, or marketing platforms — because it captures deletions and merges that a standard contact list won't reflect.
How to make your first API request
The API is accessed directly via HTTP — there's no in-product UI. To get started:
Authenticate with an access token that has the `read_users_companies` scope.
Send a GET request to `/contacts/activities`.
Page through results using the `starting_after` cursor parameter.
Control page size with `per_page` (default: 50, max: 150).
Limitations
Keep the following constraints in mind when building your integration:
Data returned | The feed returns IDs, roles, and timestamps only — no email addresses, names, or other contact attributes. |
Retention | Events are retained for 90 days via time-to-live (TTL). Events older than 90 days aren't available. |
No backfill | Only contacts created or updated after August 6, 2026 are included. There's no backfill of earlier contact history. |
At-least-once delivery | The same event can appear more than once with different cursors. Deduplicate by contact ID and event type in your application or integration. |
Best-effort writes | Occasionally, an event may be missed if a write failure occurs. This never affects the originating contact action itself. |
Deletions only | contact.deleted covers permanent deletion only — archived contacts don't appear as deleted. |
Cursor pagination only | Use pages.next to check whether more events exist and pass it as starting_after to retrieve the next page. Offset pagination isn't supported. |
Note: The Contacts Activity API is available on the Contact Activities plan in the US, EU, and AU data regions. It isn't part of Fin Standalone workspaces.