From ce8d307c73a49689f03ad9af0719994da89b4e15 Mon Sep 17 00:00:00 2001 From: Ryadh Taher Date: Wed, 12 Aug 2026 10:14:04 +0100 Subject: [PATCH 1/5] Document the team membership write endpoint in Preview Adds PUT /teams/{id} and its request payload to the Preview spec. The endpoint takes the complete desired member set rather than a delta, so the description spells out that omitted teammates are removed. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 126 ++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 13975bd..d930310 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21280,6 +21280,112 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + put: + summary: Update a team's members + 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 team. + example: '123' + schema: + type: string + tags: + - Teams + operationId: updateTeam + description: You can replace the set of teammates who belong to a team. Send + the full list of teammates the team should end up with — any teammate currently + on the team and missing from the list is removed. This makes the endpoint safe + to call on a schedule to keep Intercom in step with an external rota or workforce + management system, since sending an unchanged list makes no changes at all. + requestBody: + content: + application/json: + examples: + successful: + value: + admin_ids: + - 493881 + - 493882 + schema: + "$ref": "#/components/schemas/update_team_request" + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: team + id: '991267902' + name: team 1 + admin_ids: + - 493881 + - 493882 + schema: + "$ref": "#/components/schemas/team" + '400': + description: Bad request + content: + application/json: + examples: + Invalid admin ids: + value: + type: error.list + request_id: 8ba1e2a4-3d6f-4a1e-9c07-52c8f5b0d1aa + errors: + - code: parameter_invalid + message: admin_ids must contain only numeric admin ids + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Forbidden: + value: + type: error.list + request_id: 4dd0f4f7-2d4b-4d2f-8b98-cf1e7ba1b2c5 + errors: + - code: forbidden + message: You don't have permission to update the members of + this team + schema: + "$ref": "#/components/schemas/error" + '404': + description: Team not found + content: + application/json: + examples: + Team not found: + value: + type: error.list + request_id: 9a3e0b1c-6f27-4f5e-8c31-0f2f4a7d9e88 + errors: + - code: team_not_found + message: Team not found + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 6c1e2f83-5b47-4f0e-9d8a-3b2c1e4f7a90 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" "/ticket_states": get: summary: List all ticket states @@ -40497,6 +40603,26 @@ components: - url - locale - source_id + update_team_request: + description: | + The request payload for updating a team's membership. + `admin_ids` is the complete set of teammates who should be on the team once + the request completes, not a list of changes to apply. Any teammate currently + on the team but absent from `admin_ids` is removed. + type: object + title: Update Team Request Payload + properties: + admin_ids: + type: array + description: The ids of every teammate who should be a member of the team. + Must contain at least one id, and no more than 1000. + items: + type: integer + example: + - 493881 + - 493882 + required: + - admin_ids update_ticket_request: description: You can update a Ticket type: object From ea1d83709beef0ac4c0503ad175c4f1fe89893c9 Mon Sep 17 00:00:00 2001 From: Ryadh Taher Date: Thu, 13 Aug 2026 11:39:38 +0100 Subject: [PATCH 2/5] Document write scope and priority behaviour on team update Spell out that membership is the only writable field, that priority levels on balanced teams are read-only, and that a token acting for a teammate is held to that teammate's permissions. Adds the matching error examples. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index d930310..3ba3b7e 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21302,6 +21302,11 @@ paths: on the team and missing from the list is removed. This makes the endpoint safe to call on a schedule to keep Intercom in step with an external rota or workforce management system, since sending an unchanged list makes no changes at all. + + + A token that acts on behalf of a teammate carries that teammate's permissions: + they must be able to manage teams, and any team or teammate their access is + restricted from remains out of reach here. requestBody: content: application/json: @@ -21341,6 +21346,14 @@ paths: errors: - code: parameter_invalid message: admin_ids must contain only numeric admin ids + Field cannot be updated: + value: + type: error.list + request_id: 1c9d6f0b-7a24-4b8e-9f31-3e5a2c6b8d70 + errors: + - code: parameter_invalid + message: Only admin_ids can be updated on a team, but the request + also set name schema: "$ref": "#/components/schemas/error" '403': @@ -21356,6 +21369,13 @@ paths: - code: forbidden message: You don't have permission to update the members of this team + Cannot manage teams: + value: + type: error.list + request_id: 6b2c8e1d-4f39-4d70-8a52-9c7e1f3b0a44 + errors: + - code: forbidden + message: You don't have permission to manage teams in this workspace schema: "$ref": "#/components/schemas/error" '404': @@ -40609,6 +40629,13 @@ components: `admin_ids` is the complete set of teammates who should be on the team once the request completes, not a list of changes to apply. Any teammate currently on the team but absent from `admin_ids` is removed. + + Membership is the only part of a team this endpoint writes. Sending any other + field of the team representation returns a 400 rather than ignoring it. + + On a team that balances assignment across its members, teammates already on the + team keep their current priority level and teammates being added join as primary + members. Priority levels cannot be set through this endpoint. type: object title: Update Team Request Payload properties: From 9cd751b7f3d2d57edece16fda191ed96b136c928 Mon Sep 17 00:00:00 2001 From: Ryadh Taher Date: Thu, 13 Aug 2026 12:40:25 +0100 Subject: [PATCH 3/5] Document the conflict response and the accepted request fields Adds the 409 a caller sees when another request is already changing the same team's members, and states which fields the endpoint accepts. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 3ba3b7e..4e7b6e7 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21392,6 +21392,21 @@ paths: message: Team not found schema: "$ref": "#/components/schemas/error" + '409': + description: Another request is already changing this team's members + content: + application/json: + examples: + Conflict: + value: + type: error.list + request_id: 5e7a0c3f-8b16-4d92-a7c4-2f8b6d0e9137 + errors: + - code: conflict + message: The members of this team are being changed by another + request. Try again. + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -40630,8 +40645,9 @@ components: the request completes, not a list of changes to apply. Any teammate currently on the team but absent from `admin_ids` is removed. - Membership is the only part of a team this endpoint writes. Sending any other - field of the team representation returns a 400 rather than ignoring it. + Membership is the only part of a team this endpoint writes. `admin_ids` is the + only field it accepts; `id` and `type` are allowed so the representation can be + sent back unchanged, and any other field returns a 400 rather than being ignored. On a team that balances assignment across its members, teammates already on the team keep their current priority level and teammates being added join as primary From 94867bcfb9c1392b07f87d0c504e4ae69328cadc Mon Sep 17 00:00:00 2001 From: Ryadh Taher Date: Thu, 13 Aug 2026 12:54:07 +0100 Subject: [PATCH 4/5] Correct the description of which request fields are accepted The endpoint accepts a team read back from the API whole, so the description should not claim only three fields are allowed. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4e7b6e7..c935f97 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -40645,13 +40645,16 @@ components: the request completes, not a list of changes to apply. Any teammate currently on the team but absent from `admin_ids` is removed. - Membership is the only part of a team this endpoint writes. `admin_ids` is the - only field it accepts; `id` and `type` are allowed so the representation can be - sent back unchanged, and any other field returns a 400 rather than being ignored. + Membership is the only part of a team this endpoint writes, and `admin_ids` must + be sent in the request body rather than the query string. A team read from the + API can be sent back whole: the other fields of the representation are accepted + as long as they are unchanged. Trying to change one of them returns a 400 rather + than being ignored, as does any field a team does not have. On a team that balances assignment across its members, teammates already on the team keep their current priority level and teammates being added join as primary - members. Priority levels cannot be set through this endpoint. + members. Priority levels cannot be set through this endpoint, so + `admin_priority_level` is accepted and disregarded — it follows from `admin_ids`. type: object title: Update Team Request Payload properties: From 198e9a4c5901ccbfe9ff6e5881b79178a11f0240 Mon Sep 17 00:00:00 2001 From: Ryadh Taher Date: Thu, 13 Aug 2026 16:25:56 +0100 Subject: [PATCH 5/5] Document both meanings of a 409, and fix the endpoint description scalar The description held a colon inside an unquoted multi-line scalar, which made the whole document unparseable. Both it and the expanded 409 use block scalars. Co-Authored-By: Claude Opus 5 (1M context) --- descriptions/0/api.intercom.io.yaml | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index c935f97..48d1f66 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21297,12 +21297,12 @@ paths: tags: - Teams operationId: updateTeam - description: You can replace the set of teammates who belong to a team. Send - the full list of teammates the team should end up with — any teammate currently - on the team and missing from the list is removed. This makes the endpoint safe - to call on a schedule to keep Intercom in step with an external rota or workforce - management system, since sending an unchanged list makes no changes at all. - + description: |- + You can replace the set of teammates who belong to a team. Send the full list of + teammates the team should end up with — any teammate currently on the team and + missing from the list is removed. This makes the endpoint safe to call on a + schedule to keep Intercom in step with an external rota or workforce management + system, since sending an unchanged list makes no changes at all. A token that acts on behalf of a teammate carries that teammate's permissions: they must be able to manage teams, and any team or teammate their access is @@ -21393,7 +21393,12 @@ paths: schema: "$ref": "#/components/schemas/error" '409': - description: Another request is already changing this team's members + description: |- + Another request is already changing this team's members. Two cases are + distinguished by the message: the request was declined before anything was + written, so the team is unchanged and the same request can simply be sent + again; or the members kept changing while the request was being applied, so + it is partly applied and the team should be read again before retrying. content: application/json: examples: @@ -21405,6 +21410,15 @@ paths: - code: conflict message: The members of this team are being changed by another request. Try again. + Partly applied: + value: + type: error.list + request_id: 5e7a0c3f-8b16-4d92-a7c4-2f8b6d0e9137 + errors: + - code: conflict + message: The members of this team kept being changed by other + requests, so this one is partly applied. Read the team and + try again. schema: "$ref": "#/components/schemas/error" '401':