From 0f4916a6f2dd1c6fb53261c591e6e7cf2f0b3ae7 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Tue, 22 Sep 2026 10:58:43 +0100 Subject: [PATCH 1/4] Document read-only roles endpoints in the Preview spec Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 157 ++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 9538d528..14ab2a5a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21453,6 +21453,117 @@ paths: message: Requested resource is not available in current API version. schema: "$ref": "#/components/schemas/error" + "/roles": + get: + summary: List all roles + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Roles + operationId: listRoles + description: | + You can fetch a list of all roles in the workspace. + + Roles define what a teammate can do in a workspace. A teammate's role is + returned as part of the teammate's admin object on the teammates endpoint, + and this endpoint lets you resolve those role ids to their names and + descriptions. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: list + data: + - type: role + id: '991267902' + name: Support Lead + description: Can view and reply to conversations + schema: + "$ref": "#/components/schemas/role_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: a77dadbc-1f1e-4875-bac3-f0d09bbc214a + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + "/roles/{id}": + get: + summary: Retrieve a role + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: id + in: path + required: true + description: The unique identifier of a given role. + example: '991267902' + schema: + type: string + tags: + - Roles + operationId: retrieveRole + description: | + You can fetch the details of a single role by its id. This resolves the + role id returned on a teammate's admin object to its name and description. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: role + id: '991267902' + name: Support Lead + description: Can view and reply to conversations + schema: + "$ref": "#/components/schemas/role" + '404': + description: Role not found + content: + application/json: + examples: + Role not found: + value: + type: error.list + request_id: 3ff156ba-a66e-40d4-93ff-cb6e6afc3c9d + errors: + - code: role_not_found + message: Role not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: fc4b741b-b9f1-4ef9-92c7-eb71e9811df3 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" "/secure_mode_secrets": get: summary: List all identity verification secrets @@ -40962,6 +41073,50 @@ components: oneOf: - "$ref": "#/components/schemas/contact_reply_conversation_request" - "$ref": "#/components/schemas/admin_reply_conversation_request" + role: + title: Role + type: object + x-tags: + - Roles + description: A role defines what a teammate can do in a workspace. A teammate's + role is returned on the teammates endpoint, and this schema resolves that + role id to a name and description. + properties: + type: + type: string + description: Value is always "role" + example: role + id: + type: string + description: The id of the role + example: '991267902' + name: + type: string + description: The name of the role + example: Support Lead + description: + type: string + nullable: true + description: The description of the role + example: Can view and reply to conversations + role_list: + title: Role List + type: object + x-tags: + - Roles + description: A list of role objects in the workspace. + properties: + type: + type: string + description: The type of the object + enum: + - list + example: list + data: + type: array + description: A list of role objects + items: + "$ref": "#/components/schemas/role" search_request: description: Search using Intercoms Search APIs. type: object @@ -43957,6 +44112,8 @@ tags: {% /admonition %} - name: Reporting Data Export description: Everything about Reporting Data Export. See this [article](https://www.intercom.com/help/en/articles/12089688-api-metrics-documentation) for details on using the data to generate various metrics. +- name: Roles + description: Everything about your Roles - name: Segments description: Everything about your Segments - name: Subscription Types From 061a0ab18cc3047620940e7ef6da537e300f1b20 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Tue, 22 Sep 2026 14:54:41 +0100 Subject: [PATCH 2/4] Correct the roles endpoint descriptions The teammates endpoint already returns a role's id and name, so saying these endpoints resolve an id to a name overstated the gap. What they add is the description and the ability to list every role in the workspace. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 14ab2a5a..dd44dae0 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21467,10 +21467,10 @@ paths: description: | You can fetch a list of all roles in the workspace. - Roles define what a teammate can do in a workspace. A teammate's role is - returned as part of the teammate's admin object on the teammates endpoint, - and this endpoint lets you resolve those role ids to their names and - descriptions. + Roles define what a teammate can do in a workspace. The teammates endpoint + returns the role a teammate holds, but only the roles that are currently + assigned, and only their id and name. This endpoint lists every role in the + workspace, each with its description. responses: '200': description: successful @@ -21520,8 +21520,8 @@ paths: - Roles operationId: retrieveRole description: | - You can fetch the details of a single role by its id. This resolves the - role id returned on a teammate's admin object to its name and description. + You can fetch the details of a single role by its id, including its + description, which the teammates endpoint does not return. responses: '200': description: successful @@ -41078,9 +41078,9 @@ components: type: object x-tags: - Roles - description: A role defines what a teammate can do in a workspace. A teammate's - role is returned on the teammates endpoint, and this schema resolves that - role id to a name and description. + description: A role defines what a teammate can do in a workspace. The teammates + endpoint returns the id and name of the role a teammate holds; this schema + adds the role's description. properties: type: type: string From b3546a1eb3e25987095ddae03e54ab45404889ea Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Tue, 22 Sep 2026 16:37:39 +0100 Subject: [PATCH 3/4] Use the Preview version schema on the roles endpoints They are gated on the Preview version only, so the general intercom_version enum wrongly advertised them as callable on stable versions such as 2.16. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index dd44dae0..d9131280 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21460,7 +21460,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" tags: - Roles operationId: listRoles @@ -21508,7 +21508,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" - name: id in: path required: true From 6f31aacc13fba97bab463712a13c6fb17ffff534 Mon Sep 17 00:00:00 2001 From: robertlangner-fin Date: Tue, 22 Sep 2026 16:43:25 +0100 Subject: [PATCH 4/4] Add an example to the role_list data property Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index d9131280..a1b13a0e 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -41117,6 +41117,11 @@ components: description: A list of role objects items: "$ref": "#/components/schemas/role" + example: + - type: role + id: '991267902' + name: Support Lead + description: Can view and reply to conversations search_request: description: Search using Intercoms Search APIs. type: object