openapi: 3.1.0
info:
  title: Helpcenter Label API
  version: 1.0.0
tags:
- name: Label
paths:
  /api/v1/labels/{labelId}/users:
    get:
      tags:
      - Label
      summary: List users under a label
      description: This API lists a particular number of users under a label, based on the limit defined.
      operationId: getUsersByLabel
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/searchBy'
      - $ref: '#/components/parameters/from'
      - name: sortBy
        in: query
        description: 'Key that sorts the list of users by a specific attribute: -(@assignedTime@)'
        required: false
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          description: 'Key that sorts the list of users by a specific attribute: -(@assignedTime@)'
          maxLength: 100
          minLength: 0
          pattern: -?(assignedTime)
      - $ref: '#/components/parameters/labelId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '404':
          $ref: ./Common.json#/components/responses/urlNotFoundErrorResponse
        '200':
          $ref: '#/components/responses/userLabelListResponse'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
        - Desk.settings.READ
        - Desk.search.READ
      x-audience:
      - external-public
  /api/v1/labels:
    get:
      tags:
      - Label
      summary: List labels
      description: 'This API lists a particular number of labels, based on the limit defined. '
      operationId: getLabels
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/searchBy'
      - $ref: '#/components/parameters/from'
      - name: sortBy
        in: query
        description: 'Key that sorts the list of labels by a particular attribute: -(@createdTime@ or @modifiedTime@, or @name@)'
        required: false
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          description: 'Key that sorts the list of labels by a particular attribute: -(@createdTime@ or @modifiedTime@, or @name@)'
          maxLength: 100
          minLength: 0
          pattern: -?(createdTime|modifiedTime|name)
      - name: helpCenterId
        in: query
        description: ID of the help center from which the labels must be fetched
        required: false
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          - integer
          format: int64
          description: ID of the help center from which the labels must be fetched
          pattern: ([0-9]+)
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '200':
          $ref: '#/components/responses/labelListViewResponse'
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
        - Desk.settings.READ
      x-audience:
      - external-public
    post:
      tags:
      - Label
      summary: Create label
      description: This API creates a label in your help center.
      operationId: createLabel
      parameters:
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/createLabelPayloadJson'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '200':
          $ref: '#/components/responses/labelDetailViewResponse'
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.CREATE
        - Desk.settings.CREATE
      x-audience:
      - external-public
  /api/v1/labels/{labelId}:
    get:
      tags:
      - Label
      summary: Get details of label
      description: This API fetches the details of a particular label.
      operationId: getLabel
      parameters:
      - $ref: '#/components/parameters/labelId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '404':
          $ref: ./Common.json#/components/responses/urlNotFoundErrorResponse
        '200':
          $ref: '#/components/responses/labelDetailViewResponse'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
        - Desk.settings.READ
      x-audience:
      - external-public
    delete:
      tags:
      - Label
      summary: Delete label
      description: This API deletes a label from your help center.
      operationId: deleteLabel
      parameters:
      - $ref: '#/components/parameters/labelId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '500':
          $ref: ./Common.json#/components/responses/internalErrorResponse
        '204':
          $ref: ./Common.json#/components/responses/emptyResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.DELETE
        - Desk.settings.DELETE
      x-audience:
      - external-public
    patch:
      tags:
      - Label
      summary: Update label
      description: This API helps update the details of a label.
      operationId: updateLabel
      parameters:
      - $ref: '#/components/parameters/labelId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/updateLabelPayloadJSON'
      responses:
        '404':
          $ref: ./Common.json#/components/responses/urlNotFoundErrorResponse
        '200':
          $ref: '#/components/responses/labelDetailViewResponse'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
  /api/v1/labels/{labelId}/users/add:
    post:
      tags:
      - Label
      summary: Assign label to users
      description: This API assigns a particular label to multiple users.
      operationId: assignLabelToUsers
      parameters:
      - $ref: '#/components/parameters/labelId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/userIdsPayLoad'
      responses:
        '404':
          $ref: ./Common.json#/components/responses/urlNotFoundErrorResponse
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '204':
          $ref: ./Common.json#/components/responses/emptyResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
  /api/v1/labels/{labelId}/users/remove:
    post:
      tags:
      - Label
      summary: Remove users under a label
      description: 'This API removes all users under a particular label. '
      operationId: removeLabelsFromUsers
      parameters:
      - $ref: '#/components/parameters/labelId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/removeLabelsFromUsers_userIdsPayLoad'
      responses:
        '404':
          $ref: ./Common.json#/components/responses/urlNotFoundErrorResponse
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '204':
          $ref: ./Common.json#/components/responses/emptyResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
components:
  requestBodies:
    removeLabelsFromUsers_userIdsPayLoad:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              userIds:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: false
            required:
            - userIds
          examples:
            Valid requestBody Definitions:
              value:
                userIds:
                - '3109751143253'
                - '310975131231'
                - '310975133141'
                - '310975101849'
    userIdsPayLoad:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              userIds:
                type:
                - 'null'
                - array
                items:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                uniqueItems: false
            required:
            - userIds
          examples:
            Valid requestBody Definitions:
              value:
                userIds:
                - '3109751143253'
                - '310975131231'
                - '310975133141'
                - '310975101849'
    updateLabelPayloadJSON:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              preferences:
                $ref: ./Label.json#/components/schemas/labelPreferenceResponse
              name:
                type:
                - string
                - 'null'
                description: Name of the label
                maxLength: 100
                minLength: 0
                pattern: '[0-9a-zA-Z_\-\&\.\$\@\^\(\)\{\}\~\=\-\|\*\+\?\[\]\,\:\''\/\!\P{InBasicLatin}\s]+'
              logoId:
                type:
                - string
                - 'null'
                - integer
                format: int64
                description: ID of the logo set for the label
                pattern: ([0-9]+)
          examples:
            Valid requestBody Definitions:
              value:
                preferences:
                  shape: ROUNDED
                  bgColor: '#FFEE'
                  textColor: '#FFEE'
                name: Pro Customer
                logoId: '310975130121'
    createLabelPayloadJson:
      content:
        application/json:
          schema:
            additionalProperties: false
            allOf:
            - $ref: ./Label.json#/components/schemas/updateLabelPayloadJSON
            - type:
              - 'null'
              - object
              properties:
                helpCenterId:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  description: ID of the help center in which the label must be created
                  pattern: ([0-9]+)
            - type: object
              required:
              - helpCenterId
              - name
          examples:
            Valid requestBody Definitions:
              value:
                preferences:
                  shape: ROUNDED
                  bgColor: '#FFEE'
                  textColor: '#FFEE'
                name: Pro Customer
                helpCenterId: '310975130119'
                logoId: '310975130121'
  parameters:
    from:
      name: from
      in: query
      description: 'Index number, starting from which the users must be fetched. The default value is 1. '
      required: false
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int32
        description: 'Index number, starting from which the users must be fetched. The default value is 1. '
        minimum: 1
        pattern: ([0-9]+)
    labelId:
      name: labelId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int64
        pattern: ([0-9]+)
    searchBy:
      name: searchBy
      in: query
      description: Search keyword to use for finding a particular user. The keyword must contain at least two characters.
      required: false
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        description: Search keyword to use for finding a particular user. The keyword must contain at least two characters.
        maxLength: 100
        minLength: 0
    limit:
      name: limit
      in: query
      description: Number of users to list. The default value is 50 and the maximum value allowed is 100
      required: false
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int32
        description: Number of users to list. The default value is 50 and the maximum value allowed is 100
        maximum: 50
        minimum: 1
        pattern: ([0-9]+)
  responses:
    labelDetailViewResponse:
      description: labelDetailViewResponse template definitions
      content:
        application/json:
          schema:
            additionalProperties: false
            allOf:
            - $ref: ./Label.json#/components/schemas/labelMetaResponse
            - type:
              - 'null'
              - object
              properties:
                modifiedTime:
                  type:
                  - string
                  - 'null'
                  maxLength: 100
                  minLength: 0
                  pattern: (((19|20)\d\d)[-/.]{1}(0?[1-9]|1[012])[-/.]{1}(0?[1-9]|[12][0-9]|3[01])(T)([01]?[0-9]|2[0-3]):[0-5]?[0-9]:[0-5]?[0-9]([/.][\d]{0,3})?(Z))
                creator:
                  $ref: ./Label.json#/components/schemas/creatorResponse
                modifier:
                  $ref: ./Label.json#/components/schemas/creatorResponse
                count:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int32
                  pattern: ([0-9]+)
                createdTime:
                  type:
                  - string
                  - 'null'
                  maxLength: 100
                  minLength: 0
                  pattern: (((19|20)\d\d)[-/.]{1}(0?[1-9]|1[012])[-/.]{1}(0?[1-9]|[12][0-9]|3[01])(T)([01]?[0-9]|2[0-3]):[0-5]?[0-9]:[0-5]?[0-9]([/.][\d]{0,3})?(Z))
                helpCenterId:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
              required:
              - count
              - createdTime
              - creator
              - helpCenterId
              - modifiedTime
              - modifier
          examples:
            Valid responses Definitions:
              value:
                modifiedTime: 1505797130000
                preferences:
                  shape: ROUNDED
                  bgColor: '#FFEE'
                  textColor: '#FFEE'
                creator:
                  photoURL: https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315
                  name: SupportAdmin
                  id: '310975130121'
                modifier:
                  photoURL: https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315
                  name: SupportAdmin
                  id: '310975130121'
                name: Pro Customer
                count: '892'
                createdTime: 1505797130000
                id: '310975130110'
                helpCenterId: '310975130119'
                logoUrl: https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48
    userLabelListResponse:
      description: userLabelListResponse template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              data:
                $ref: ./Label.json#/components/schemas/userLabelData
            required:
            - data
          examples:
            Valid responses Definitions:
              value:
                data:
                - photoUrl: null
                  emailAddress: carol@zylker.com
                  name: svega RM
                  userType: ENDUSER
                  assignee:
                    photoUrl: https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315
                    name: Chris
                    id: '6000000015895'
                  id: '6000000032907'
                  assignedTime: 1565336864000
                  status: ACTIVE
    labelListViewResponse:
      description: labelListViewResponse template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              data:
                $ref: ./Label.json#/components/schemas/labelData
            required:
            - data
          examples:
            Valid responses Definitions:
              value:
                data:
                - modifiedTime: 1505797130000
                  preferences:
                    shape: ROUNDED
                    bgColor: '#FFEE'
                    textColor: '#FFEE'
                  creator:
                    photoURL: https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315
                    name: SupportAdmin
                    id: '310975130121'
                  modifier:
                    photoURL: https://desk.zoho.com/portal/api/user/6000000015895/photo?orgId=143315
                    name: SupportAdmin
                    id: '310975130121'
                  name: Pro Customer
                  count: '892'
                  createdTime: 1505797130000
                  id: '310975130110'
                  helpCenterId: '310975130119'
                  logoUrl: https://desk.zoho.com/portal/api/publicImages/310975130121?portalId=5c9470fcc808cc98932703e28221d6c302e105dc4da8b23fafb6719abeecaa48
  securitySchemes:
    iam-oauth2-schema:
      $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema
x-entity: Helpcenter