From e6498fc706501a0718b82523bb1c93faaecc1f37 Mon Sep 17 00:00:00 2001 From: Varshini Suresh Date: Wed, 5 Aug 2026 17:57:25 +0100 Subject: [PATCH 1/3] Add GET /contacts/activities to the Preview spec Adds the Preview endpoint that lists contact activity events (creation, merge, deletion) for a workspace, with cursor pagination. Mirrors the developer-docs reference. Co-Authored-By: Claude Opus 4.8 (1M context) --- descriptions/0/api.intercom.io.yaml | 142 ++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 2ecca2e..6fdbc56 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -9201,6 +9201,77 @@ paths: order: ascending pagination: per_page: 5 + "/contacts/activities": + get: + summary: List all contact activities + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version_preview" + - name: per_page + in: query + required: false + description: The number of results to return per page. Defaults to 50, minimum 1, maximum 150. + schema: + type: integer + default: 50 + minimum: 1 + maximum: 150 + - name: starting_after + in: query + required: false + description: The cursor value from `pages.next.starting_after` in a previous response. Used to paginate through results. + schema: + type: string + tags: + - Contacts + operationId: ListContactActivities + description: | + You can fetch a list of contact activity events for your workspace, such as when contacts are created, merged, or deleted. Events are returned oldest first. + + This endpoint requires an OAuth token with the `read_users_companies` scope. + {% admonition type="warning" name="Pagination" %} + You can use pagination to limit the number of results returned. The default is `50` results per page, with a maximum of `150`. + See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param. + {% /admonition %} + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: list + data: + - type: contact_activity + id: '1717000000000.0000a1' + event_type: contact.created + contact_id: 6329bd9ffe4e2e91dc5d6a1e + role: user + created_at: 1717000000 + pages: + type: pages + per_page: 50 + next: + starting_after: '1717000000000.0000a1' + schema: + "$ref": "#/components/schemas/contact_activity_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" "/contacts": get: summary: List all contacts @@ -29634,6 +29705,77 @@ components: type: boolean description: Whether the contact is deleted or not. example: true + contact_activity: + title: Contact Activity + type: object + description: An activity event that occurred for a contact, such as creation, merge, or deletion. + properties: + type: + type: string + description: Always contact_activity + enum: + - contact_activity + example: contact_activity + id: + type: string + description: The unique identifier for the activity event. + example: '1717000000000.0000a1' + event_type: + type: string + description: The type of activity event, e.g. contact.created, contact.merged, contact.deleted, contact.merge_failed. + example: contact.created + contact_id: + type: string + description: The unique identifier for the contact the event relates to. + example: 6329bd9ffe4e2e91dc5d6a1e + external_id: + type: string + nullable: true + description: The external identifier of the contact, if one is set. + example: user-42 + role: + type: string + nullable: true + description: The role of the contact at the time of the event, either user, lead, or visitor. + example: user + merge_source_id: + type: string + nullable: true + description: For merge events, the identifier of the contact that was merged away. + example: 5f7f0d217c3f2e001a4e8b12 + merge_target_id: + type: string + nullable: true + description: For merge events, the identifier of the contact that was merged into. + example: 6329bd9ffe4e2e91dc5d6a1e + failure_reason: + type: string + nullable: true + description: For failed events, the reason the activity did not succeed. + example: duplicate_external_id + created_at: + type: integer + format: date-time + description: The time the activity event occurred, as a Unix timestamp in seconds. + example: 1717000000 + contact_activity_list: + title: Contact Activity List + type: object + description: A paginated list of contact activity events. + properties: + type: + type: string + description: Always list + enum: + - list + example: list + data: + type: array + description: The list of contact activity objects. + items: + "$ref": "#/components/schemas/contact_activity" + pages: + "$ref": "#/components/schemas/cursor_pages" contact_list: title: Contact List type: object From 8569179a66f380a61e8185a6ee4add5b375d118d Mon Sep 17 00:00:00 2001 From: Varshini Suresh Date: Thu, 6 Aug 2026 13:57:32 +0100 Subject: [PATCH 2/3] Show every contact activity event type in the 200 example Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 62 ++++++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 6fdbc56..4602f41 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -9208,7 +9208,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version_preview" + "$ref": "#/components/schemas/intercom_version" - name: per_page in: query required: false @@ -9228,9 +9228,8 @@ paths: - Contacts operationId: ListContactActivities description: | - You can fetch a list of contact activity events for your workspace, such as when contacts are created, merged, or deleted. Events are returned oldest first. + You can fetch a list of contact activity events for your workspace, such as when contacts are created, role updated, merged, or deleted. Events are returned oldest first. - This endpoint requires an OAuth token with the `read_users_companies` scope. {% admonition type="warning" name="Pagination" %} You can use pagination to limit the number of results returned. The default is `50` results per page, with a maximum of `150`. See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param. @@ -9249,13 +9248,44 @@ paths: id: '1717000000000.0000a1' event_type: contact.created contact_id: 6329bd9ffe4e2e91dc5d6a1e - role: user + external_id: user-42 + role: lead created_at: 1717000000 + - type: contact_activity + id: '1717000100000.0000b2' + event_type: contact.role_updated + contact_id: 6329bd9ffe4e2e91dc5d6a1e + external_id: user-42 + role: user + created_at: 1717000100 + - type: contact_activity + id: '1717000200000.0000c3' + event_type: contact.merged + contact_id: 6329bd9ffe4e2e91dc5d6a1e + external_id: user-42 + role: user + merge_source_id: 5f7f0d217c3f2e001a4e8b12 + merge_target_id: 6329bd9ffe4e2e91dc5d6a1e + created_at: 1717000200 + - type: contact_activity + id: '1717000300000.0000d4' + event_type: contact.merge_failed + contact_id: 5f7f0d217c3f2e001a4e8b12 + merge_source_id: 5f7f0d217c3f2e001a4e8b12 + merge_target_id: 6329bd9ffe4e2e91dc5d6a1e + failure_reason: Merge source_user cannot have role='user_role' + created_at: 1717000300 + - type: contact_activity + id: '1717000400000.0000e5' + event_type: contact.deleted + contact_id: 6329bd9ffe4e2e91dc5d6a1e + role: user + created_at: 1717000400 pages: type: pages per_page: 50 next: - starting_after: '1717000000000.0000a1' + starting_after: '1717000400000.0000e5' schema: "$ref": "#/components/schemas/contact_activity_list" '401': @@ -29775,7 +29805,27 @@ components: items: "$ref": "#/components/schemas/contact_activity" pages: - "$ref": "#/components/schemas/cursor_pages" + type: object + description: Pagination information. + properties: + type: + type: string + example: pages + enum: + - pages + per_page: + type: integer + description: The number of results per page. + example: 10 + next: + type: object + nullable: true + description: Cursor for the next page of results. + properties: + starting_after: + type: string + description: The cursor value to use for the next page. + example: 1717000000000.0000a1 contact_list: title: Contact List type: object From 085667a1ac0a1b0f068e7c6b67bf7ba5fc316eb9 Mon Sep 17 00:00:00 2001 From: Varshini Suresh Date: Thu, 6 Aug 2026 13:59:51 +0100 Subject: [PATCH 3/3] Constrain contact activity event_type to the five emitted values Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4602f41..a3e8773 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -29752,7 +29752,13 @@ components: example: '1717000000000.0000a1' event_type: type: string - description: The type of activity event, e.g. contact.created, contact.merged, contact.deleted, contact.merge_failed. + description: The type of activity event. + enum: + - contact.created + - contact.role_updated + - contact.deleted + - contact.merged + - contact.merge_failed example: contact.created contact_id: type: string