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.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts