Zoho Team API

openapi: 3.2.0
info:
  title: Helpcenter Team API
  version: 1.0.0
tags:
- name: Team
paths:
  /api/v1/departments/{departmentId}/teams:
    get:
      tags:
      - Team
      summary: List teams in department
      description: This API fetches details of all the teams in a particular department.
      operationId: getTeamsInDepartment
      parameters:
      - name: departmentId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/teamListResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.READ
        - Desk.basic.READ
      x-audience:
      - external-public
  /api/v1/teams:
    get:
      tags:
      - Team
      summary: List teams from all associated departments
      description: This API fetches details of all teams created in all departments to which the current user belongs.
      operationId: getTeams
      parameters:
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/teamListResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.READ
        - Desk.basic.READ
      x-audience:
      - external-public
    post:
      tags:
      - Team
      summary: Create team
      description: This API creates a team in your help desk portal.
      operationId: createTeam
      parameters:
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/teamRequestJson'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '200':
          $ref: '#/components/responses/teamResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.CREATE
        - Desk.basic.CREATE
      x-audience:
      - external-public
  /api/v1/teams/{team_id}/deleteTeam:
    post:
      tags:
      - Team
      summary: Delete team
      description: This API deletes an existing team from your help desk portal. To reassign the open and on hold tickets and tasks of the deleted team to a different team, pass the <b>ticketNewTeam</b>, <b>taskNewTeam</b>, <b>ticketNewAgent</b>, and <b>taskNewAgent</b> team parameters in the API request. If you do not want to assign the tickets to another team, pass the values of <b>ticketNewTeam</b> and <b>ticketNewAgent</b> as null. However, in the case of tasks, either <b>taskNewTeam</b> or <b>taskNewAgent</b> must have a valid value. Both parameters cannot be passed as null.
      operationId: deleteTeam
      parameters:
      - $ref: '#/components/parameters/team_id'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/deleteTeamRequest'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse
        '200':
          $ref: ./Common.json#/components/responses/emptyResponse
      security:
      - iam-oauth2-schema:
        - Desk.settings.DELETE
        - Desk.basic.DELETE
      x-audience:
      - external-public
  /api/v1/teams/{teamId}/associables:
    get:
      tags:
      - Team
      summary: List associable teams
      description: This API lists the other teams that can be added as sub-teams to the current team.
      operationId: getSubTeamsIds
      parameters:
      - $ref: '#/components/parameters/teamId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/associableTeamListResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.READ
        - Desk.basic.READ
      x-audience:
      - external-public
  /api/v1/roles/{role_id}/teams:
    get:
      tags:
      - Team
      summary: List associated teams for a role
      description: This API fetches details of all the teams associated with a particular role.
      operationId: getAssociatedTeamsForRole
      parameters:
      - name: role_id
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/teamListResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.READ
        - Desk.basic.READ
      x-audience:
      - external-public
  /api/v1/agents/{agentId}/teams:
    get:
      tags:
      - Team
      summary: List associated teams of agent
      description: This API fetches details of all the teams to which an agent belongs.
      operationId: listAssociatedTeamsForAgent
      parameters:
      - name: agentId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/teamListResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.READ
        - Desk.basic.READ
      x-audience:
      - external-public
  /api/v1/teams/{team_id}/members:
    get:
      tags:
      - Team
      summary: List details of team members
      description: This API fetches details of all the members of a particular team.
      operationId: getTeamMembersDetails
      parameters:
      - name: include
        in: query
        description: Secondary information related to the team. Values allowed are @profile@, @role@. You can include all two values by separating them with commas in the API request.
        required: false
        style: simple
        explode: true
        schema:
          type:
          - 'null'
          - array
          description: Secondary information related to the team. Values allowed are @profile@, @role@. You can include all two values by separating them with commas in the API request.
          items:
            type:
            - string
            - 'null'
            enum:
            - profile
            - role
            maxLength: 100
            minLength: 0
          maxItems: 2
          uniqueItems: true
      - $ref: '#/components/parameters/team_id'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/teamMembersListResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.READ
        - Desk.basic.READ
      x-audience:
      - external-public
  /api/v1/teams/{teamId}:
    get:
      tags:
      - Team
      summary: Get team
      description: This API fetches the details of a team.
      operationId: getTeam
      parameters:
      - $ref: '#/components/parameters/teamId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/teamResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.READ
        - Desk.basic.READ
      x-audience:
      - external-public
  /api/v1/teams/{team_id}:
    patch:
      tags:
      - Team
      summary: Update team
      description: This API updates details of an existing team.
      operationId: updateTeam
      parameters:
      - $ref: '#/components/parameters/team_id'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/teamUpdateJson'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '200':
          $ref: '#/components/responses/teamResponse'
      security:
      - iam-oauth2-schema:
        - Desk.settings.UPDATE
        - Desk.basic.UPDATE
      x-audience:
      - external-public
components:
  requestBodies:
    teamRequestJson:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              roles:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: true
              departmentId:
                type:
                - string
                - 'null'
                - integer
                format: int64
                pattern: ([0-9]+)
              name:
                type:
                - string
                - 'null'
                maxLength: 50
                minLength: 1
                pattern: ([0-9a-zA-Z_\-\.\$@\?\,\:\'\/\!\P{InBasicLatin}\s])+
              description:
                type:
                - string
                - 'null'
                maxLength: 255
                minLength: 0
                pattern: ([0-9a-zA-Z_\-\.\$@\?\,\:\'\/\!\P{InBasicLatin}\s])+
              subTeams:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: true
              agents:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: true
            required:
            - departmentId
            - name
          examples:
            Valid requestBody Definitions:
              value:
                rolesWithSubordinates:
                - '6000000008684'
                - '6000000008686'
                departmentId: '6000000009893'
                roles:
                - '6000000011307'
                - '6000000011309'
                - '6000000011311'
                name: Sales Representatives
                description: Sales teams for customer engagement.
                subTeams:
                - '6000000012001'
                agents:
                - '6000000009086'
    teamUpdateJson:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              roles:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: true
              name:
                type:
                - string
                - 'null'
                maxLength: 50
                minLength: 1
                pattern: ([0-9a-zA-Z_\-\.\$@\?\,\:\'\/\!\P{InBasicLatin}\s])+
              description:
                type:
                - string
                - 'null'
                maxLength: 255
                minLength: 0
                pattern: ([0-9a-zA-Z_\-\.\$@\?\,\:\'\/\!\P{InBasicLatin}\s])+
              subTeams:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: true
              agents:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: true
          examples:
            Valid requestBody Definitions:
              value:
                roles:
                - '6000000011307'
                - '6000000011311'
                name: Sales Reps.
                description: Sales teams for winning customers.
                subTeams:
                - '6000000011303'
                agents:
                - '6000000009086'
    deleteTeamRequest:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              ticketNewAgent:
                type:
                - string
                - 'null'
                - integer
                format: int64
                pattern: ([0-9]+)
              ticketNewTeam:
                type:
                - string
                - 'null'
                - integer
                format: int64
                pattern: ([0-9]+)
              taskNewTeam:
                type:
                - string
                - 'null'
                - integer
                format: int64
                pattern: ([0-9]+)
              taskNewAgent:
                type:
                - string
                - 'null'
                - integer
                format: int64
                pattern: ([0-9]+)
            required:
            - taskNewAgent
            - taskNewTeam
            - ticketNewAgent
            - ticketNewTeam
          examples:
            Valid requestBody Definitions:
              value:
                ticketNewAgent: '5000000013005'
                ticketNewTeam: '5000000013001'
                taskNewTeam: '5000000013001'
                taskNewAgent: '5000000013009'
  parameters:
    teamId:
      name: teamId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int64
        pattern: ([0-9]+)
    team_id:
      name: team_id
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int64
        pattern: ([0-9]+)
  responses:
    associableTeamListResponse:
      description: associableTeamListResponse template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              teams:
                $ref: ./Team.json#/components/schemas/teamIds
            required:
            - teams
          examples:
            Valid responses Definitions:
              value:
                teams:
                - 6000000011303
                - 6000000017021
                - 6000000017023
                - 6000000016013
                - 6000000017017
                - 6000000016015
                - 6000000017019
                - 6000000017013
                - 6000000017015
                - 6000000017009
                - 6000000012001
                - 6000000017011
                - 6000000017005
                - 6000000016025
                - 6000000017007
                - 6000000017059
                - 6000000016027
                - 6000000017001
                - 6000000016029
                - 6000000017003
                - 6000000016031
                - 6000000016017
                - 6000000015001
                - 6000000016019
                - 6000000016021
    teamListResponse:
      description: teamListResponse template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              teams:
                $ref: ./Team.json#/components/schemas/teamResponseArray
            required:
            - teams
          examples:
            Valid responses Definitions:
              value:
                teams:
                - rolesWithSubordinates: []
                  departmentId: '60000000839483'
                  roles:
                  - '60000000098623'
                  name: Sales Reps.
                  description: Sales teams for winning customers.
                  derivedAgents:
                  - '6000000011313'
                  - '60000000120230'
                  id: '6000000083003'
                  subTeams: []
                  logoUrl: null
                  agents: []
                - rolesWithSubordinates: []
                  departmentId: '60000000839483'
                  roles: []
                  name: Support Teams
                  description: Support teams for solving customer issues.
                  derivedAgents:
                  - '6000000011313'
                  id: '6000000083034'
                  subTeams: []
                  logoUrl: null
                  agents:
                  - '6000000011313'
    teamMembersListResponse:
      description: teamMembersListResponse template definitions
      content:
        application/json:
          schema:
            allOf:
            - type: object
              properties:
                members:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type:
                        - 'null'
                        - object
                        additionalProperties: false
                        maxProperties: 2
                        minProperties: 2
                        properties:
                          name:
                            type:
                            - string
                            - 'null'
                            maxLength: 100
                            minLength: 0
                          id:
                            type:
                            - string
                            - 'null'
                            - integer
                            format: int64
                            pattern: ([0-9]+)
                        required:
                        - id
                        - name
                      profile:
                        type:
                        - 'null'
                        - object
                        additionalProperties: false
                        maxProperties: 2
                        minProperties: 2
                        properties:
                          name:
                            type:
                            - string
                            - 'null'
                            maxLength: 50
                            minLength: 0
                          id:
                            type:
                            - string
                            - 'null'
                            - integer
                            format: int64
                            pattern: ([0-9]+)
                        required:
                        - id
                        - name
            - type:
              - 'null'
              - object
              additionalProperties: false
              properties:
                members:
                  $ref: ./Team.json#/components/schemas/teamMembersDetailsList
              required:
              - members
          examples:
            Valid responses Definitions:
              value:
                members:
                - firstName: ''
                  lastName: John
                  photoURL: https://contacts.zoho.com/file?t=user&ID=437793
                  roleId: '7000000012324'
                  profileId: '7000000012339'
                  emailId: john@zylker.com
                  id: '7000000013328'
                  zuid: '437793'
                - firstName: Steve
                  lastName: Kyle
                  photoURL: null
                  roleId: '7000000012324'
                  profileId: '7000000012339'
                  emailId: kyle@zylker.com
                  id: '7000000012958'
                  zuid: '5625416'
    teamResponse:
      description: teamResponse template definitions
      content:
        application/json:
          schema:
            additionalProperties: false
            allOf:
            - $ref: ./Team.json#/components/schemas/teamJson
            - type:
              - 'null'
              - object
              properties:
                derivedAgents:
                  type:
                  - 'null'
                  - array
                  items:
                    type:
                    - string
                    - 'null'
                    - integer
                    format: int64
                    pattern: ([0-9]+)
                  uniqueItems: true
                id:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                logoUrl:
                  type:
                  - string
                  - 'null'
                  maxLength: 200
                  minLength: 0
                  pattern: (^(ht|f)tp(s?)\://[-.\w]*(/?)([a-zA-Z0-9\-\.\?\,\:\'/\\+=&amp;%\$#_@]*)?$)
              required:
              - derivedAgents
              - id
              - logoUrl
          examples:
            Valid responses Definitions:
              value:
                rolesWithSubordinates:
                - '6000000008684'
                - '6000000008686'
                departmentId: '6000000009893'
                roles:
                - '6000000011311'
                - '6000000011307'
                name: Sales Reps.
                description: Sales teams for winning customers.
                derivedAgents:
                - '6000000009086'
                - '6000000012003'
                id: '6000000014007'
                subTeams:
                - '6000000011303'
                logoUrl: null
                agents:
                - '6000000009086'
  securitySchemes:
    iam-oauth2-schema:
      $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema
x-entity: Helpcenter