diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 13975bd..395fdab 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -21280,6 +21280,173 @@ 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: updateTeamMembers + 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 + restricted from remains out of reach here. + requestBody: + content: + application/json: + examples: + successful: + value: + admin_ids: + - 493881 + - 493882 + schema: + "$ref": "#/components/schemas/update_team_members_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 + 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 + changed name + schema: + "$ref": "#/components/schemas/error" + '403': + description: |- + Two codes are returned here and they mean different things. `api_plan_restricted` + means the endpoint is not available to this workspace at all, so no request will + succeed until it is enabled. `forbidden` means the workspace has the endpoint but + the teammate this token acts for may not make this particular change. + content: + application/json: + examples: + Not available for this workspace: + value: + type: error.list + request_id: 2f7b9c04-8e15-4a63-b0d7-6c41e9a3f582 + errors: + - code: api_plan_restricted + message: Updating team memberships via the API is not available + for this workspace + 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 + 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': + 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" + '409': + 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: + 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. + 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': + 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 +40664,39 @@ components: - url - locale - source_id + update_team_members_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. + + Membership is the only part of a team this endpoint writes, and the request is + read from the body: a parameter sent in the query string is rejected rather than + applied. A team read from the API can be sent back whole, since 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 here, so `admin_priority_level` follows + from `admin_ids`: it is accepted when sent back unchanged and returns a 400 when + the request tries to change it. + type: object + title: Update Team Members 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