From bd755d32a9910d05b9041b1c7af6689e02c504e6 Mon Sep 17 00:00:00 2001 From: Marc <97827744+marcmlc@users.noreply.github.com> Date: Tue, 28 Apr 2026 17:54:51 +0100 Subject: [PATCH 1/6] Add users/companies fields to tag_basic schema (preview) Preview version of POST /tags now skips missing entities instead of returning 404. The response includes users and companies arrays, each containing objects with id and untagged fields. Companion to intercom/intercom#502233. Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 79 ++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 25 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 2caca1b..d282394 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -14828,6 +14828,22 @@ paths: type: tag id: '105' name: test + users: [] + companies: [] + Company not found - tag created, entity skipped: + value: + type: tag + id: '105' + name: test + users: [] + companies: [] + User not found - tag created, entity skipped: + value: + type: tag + id: '105' + name: test + users: [] + companies: [] schema: "$ref": "#/components/schemas/tag_basic" '400': @@ -14844,27 +14860,6 @@ paths: message: invalid tag parameters schema: "$ref": "#/components/schemas/error" - '404': - description: User not found - content: - application/json: - examples: - Company not found: - value: - type: error.list - request_id: 23c998cc-32b8-435d-9653-932c15809460 - errors: - - code: company_not_found - message: Company Not Found - User not found: - value: - type: error.list - request_id: 7358f78d-f122-45dd-a2e1-c2261300c38a - errors: - - code: not_found - message: User Not Found - schema: - "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -14897,14 +14892,14 @@ paths: summary: Invalid parameters value: test: invalid - company_not_found: - summary: Company not found + company_not_found_entity_skipped: + summary: Company not found - tag created, entity skipped value: name: test companies: - company_id: '123' - user_not_found: - summary: User not found + user_not_found_entity_skipped: + summary: User not found - tag created, entity skipped value: name: test users: @@ -27333,6 +27328,40 @@ components: type: string description: The name of the tag example: Test tag + users: + type: array + nullable: true + description: The users that were tagged or untagged. Only present on preview + API versions when tagging or untagging users. + items: + type: object + properties: + id: + type: string + description: The Intercom ID of the user. + example: '6329e838deab40166d1a53f7' + untagged: + type: boolean + description: Whether the user was untagged (true) or tagged (false). + example: false + example: [] + companies: + type: array + nullable: true + description: The companies that were tagged or untagged. Only present on + preview API versions when tagging or untagging companies. + items: + type: object + properties: + id: + type: string + description: The Intercom ID of the company. + example: '6329e838deab40166d1a5400' + untagged: + type: boolean + description: Whether the company was untagged (true) or tagged (false). + example: false + example: [] tag_company_request: description: You can tag a single company or a list of companies. type: object From f1380b620a9fa067f481d9d5ef7b70aeda366515 Mon Sep 17 00:00:00 2001 From: Marc <97827744+marcmlc@users.noreply.github.com> Date: Tue, 28 Apr 2026 17:58:52 +0100 Subject: [PATCH 2/6] Remove preview-specific wording from field descriptions Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index d282394..2aff6fa 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -27331,8 +27331,8 @@ components: users: type: array nullable: true - description: The users that were tagged or untagged. Only present on preview - API versions when tagging or untagging users. + description: The users that were tagged or untagged. Present when tagging + or untagging users via POST /tags. items: type: object properties: @@ -27348,8 +27348,8 @@ components: companies: type: array nullable: true - description: The companies that were tagged or untagged. Only present on - preview API versions when tagging or untagging companies. + description: The companies that were tagged or untagged. Present when tagging + or untagging companies via POST /tags. items: type: object properties: From d0148166ff5ef3f4966e9ed06bd755fda25fcd90 Mon Sep 17 00:00:00 2001 From: Marc <97827744+marcmlc@users.noreply.github.com> Date: Tue, 28 Apr 2026 17:59:58 +0100 Subject: [PATCH 3/6] Simplify field descriptions Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 2aff6fa..4a121b4 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -27331,8 +27331,7 @@ components: users: type: array nullable: true - description: The users that were tagged or untagged. Present when tagging - or untagging users via POST /tags. + description: The users that were tagged or untagged. items: type: object properties: @@ -27348,8 +27347,7 @@ components: companies: type: array nullable: true - description: The companies that were tagged or untagged. Present when tagging - or untagging companies via POST /tags. + description: The companies that were tagged or untagged. items: type: object properties: From b05050d4c4b4c1199c960946a8cf9ccff5d8307c Mon Sep 17 00:00:00 2001 From: Marc <97827744+marcmlc@users.noreply.github.com> Date: Wed, 29 Apr 2026 09:33:37 +0100 Subject: [PATCH 4/6] Update api.intercom.io.yaml --- descriptions/0/api.intercom.io.yaml | 28 +--------------------------- 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4a121b4..9eafdc2 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -14829,21 +14829,7 @@ paths: id: '105' name: test users: [] - companies: [] - Company not found - tag created, entity skipped: - value: - type: tag - id: '105' - name: test - users: [] - companies: [] - User not found - tag created, entity skipped: - value: - type: tag - id: '105' - name: test - users: [] - companies: [] + companies: [{ "id": "valid-123" }] schema: "$ref": "#/components/schemas/tag_basic" '400': @@ -14892,18 +14878,6 @@ paths: summary: Invalid parameters value: test: invalid - company_not_found_entity_skipped: - summary: Company not found - tag created, entity skipped - value: - name: test - companies: - - company_id: '123' - user_not_found_entity_skipped: - summary: User not found - tag created, entity skipped - value: - name: test - users: - - id: '123' "/tags/{id}": get: summary: Find a specific tag From e7210e3c0a348733e9f19714793e03a44ca2fc62 Mon Sep 17 00:00:00 2001 From: Marc <97827744+marcmlc@users.noreply.github.com> Date: Wed, 29 Apr 2026 13:44:16 +0100 Subject: [PATCH 5/6] Rename untagged to tagged in tag response schema Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 9eafdc2..a905b8a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -27313,10 +27313,10 @@ components: type: string description: The Intercom ID of the user. example: '6329e838deab40166d1a53f7' - untagged: + tagged: type: boolean - description: Whether the user was untagged (true) or tagged (false). - example: false + description: Whether the user was tagged (true) or untagged (false). + example: true example: [] companies: type: array @@ -27329,10 +27329,10 @@ components: type: string description: The Intercom ID of the company. example: '6329e838deab40166d1a5400' - untagged: + tagged: type: boolean - description: Whether the company was untagged (true) or tagged (false). - example: false + description: Whether the company was tagged (true) or untagged (false). + example: true example: [] tag_company_request: description: You can tag a single company or a list of companies. From afe54784cc128ff38a3e2c90c9c57da519f6ccc4 Mon Sep 17 00:00:00 2001 From: Marc <97827744+marcmlc@users.noreply.github.com> Date: Wed, 29 Apr 2026 13:51:12 +0100 Subject: [PATCH 6/6] Move users/companies fields to dedicated tag_create_response schema The users and companies arrays are only relevant to POST /tags responses. Using allOf to extend tag_basic keeps the shared schema clean for GET endpoints that also reference it. Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 76 ++++++++++++++++------------- 1 file changed, 42 insertions(+), 34 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a905b8a..df49fd6 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -14829,9 +14829,9 @@ paths: id: '105' name: test users: [] - companies: [{ "id": "valid-123" }] + companies: [{ "id": "valid-123", "tagged": true }] schema: - "$ref": "#/components/schemas/tag_basic" + "$ref": "#/components/schemas/tag_create_response" '400': description: Invalid parameters content: @@ -27302,38 +27302,46 @@ components: type: string description: The name of the tag example: Test tag - users: - type: array - nullable: true - description: The users that were tagged or untagged. - items: - type: object - properties: - id: - type: string - description: The Intercom ID of the user. - example: '6329e838deab40166d1a53f7' - tagged: - type: boolean - description: Whether the user was tagged (true) or untagged (false). - example: true - example: [] - companies: - type: array - nullable: true - description: The companies that were tagged or untagged. - items: - type: object - properties: - id: - type: string - description: The Intercom ID of the company. - example: '6329e838deab40166d1a5400' - tagged: - type: boolean - description: Whether the company was tagged (true) or untagged (false). - example: true - example: [] + tag_create_response: + title: Create or Update Tag Response + description: The response for creating or updating a tag, including the entities + that were tagged or untagged. + allOf: + - "$ref": "#/components/schemas/tag_basic" + - type: object + properties: + users: + type: array + nullable: true + description: The users that were tagged or untagged. + items: + type: object + properties: + id: + type: string + description: The Intercom ID of the user. + example: '6329e838deab40166d1a53f7' + tagged: + type: boolean + description: Whether the user was tagged (true) or untagged (false). + example: true + example: [] + companies: + type: array + nullable: true + description: The companies that were tagged or untagged. + items: + type: object + properties: + id: + type: string + description: The Intercom ID of the company. + example: '6329e838deab40166d1a5400' + tagged: + type: boolean + description: Whether the company was tagged (true) or untagged (false). + example: true + example: [] tag_company_request: description: You can tag a single company or a list of companies. type: object