Add team membership write endpoint to Preview spec (#619)

Author: ryadhtaher-coder

descriptions/0/api.intercom.io.yaml

@@ -21281,6 +21281,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
@@ -40514,6 +40681,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