Zoho User API

openapi: 3.1.0
info:
  title: Helpcenter User API
  version: 1.0.0
tags:
- name: User
paths:
  /api/v1/users/{userId}:
    get:
      tags:
      - User
      summary: Get User Details
      description: This API fetches the details of a particular help center user.
      operationId: getUserDetails
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/userDetailViewJson'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '500':
          $ref: ./Common.json#/components/responses/internalErrorResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
        - Desk.settings.READ
        - Desk.basic.READ
      x-audience:
      - external-public
    patch:
      tags:
      - User
      summary: Update User Details
      description: 'This API helps update the details of a particular help center user. '
      operationId: updateUserDetails
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/updateUserJson'
      responses:
        '200':
          $ref: '#/components/responses/userDetailViewJson'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '500':
          $ref: ./Common.json#/components/responses/internalErrorResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
  /api/v1/users/{userId}/groups/associate:
    post:
      tags:
      - User
      summary: Associate Groups To Users
      description: This API adds a user to the groups specified.
      operationId: associateGroupsToUsers
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/userGroupInputJson'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '200':
          $ref: '#/components/responses/massActionListViewResponse'
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
  /api/v1/users/{userId}/labels:
    get:
      tags:
      - User
      summary: Get User Labels
      description: This API lists a particular number of labels associated with a user, based on the limit defined.
      operationId: getUserLabels
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/userLabelJson'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '500':
          $ref: ./Common.json#/components/responses/internalErrorResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
        - Desk.settings.READ
      x-audience:
      - external-public
  /api/v1/users/{userId}/labels/remove:
    post:
      tags:
      - User
      summary: Remove Labels From User
      description: This API removes the labels you specify from a particular user.
      operationId: removeLabelsFromUser
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: ./Label.json#/components/requestBodies/labelIdsJson
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '200':
          $ref: '#/components/responses/massActionListViewResponse'
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
  /api/v1/users/{userId}/groups/dissociate:
    post:
      tags:
      - User
      summary: Delete Groups From Users
      description: This API removes a user from the groups specified.
      operationId: deleteGroupsFromUsers
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: ./HelpcenterGroups.json#/components/requestBodies/groupIds
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '200':
          $ref: '#/components/responses/massActionListViewResponse'
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
  /api/v1/users/{userId}/anonymize:
    post:
      tags:
      - User
      summary: Delete End User
      description: This API permanently deletes all identifying information about a user from your help center.
      operationId: deleteEndUser
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/anonymizeInpJson'
      responses:
        '404':
          $ref: ./Common.json#/components/responses/urlNotFoundErrorResponse
        '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.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
  /api/v1/users:
    get:
      tags:
      - User
      summary: Get Users
      description: This API lists a particular number of help center users, based on the limit defined. It also helps you search for specific users.
      operationId: getUsers
      parameters:
      - name: include
        in: query
        description: Additional information related to the user. Value allowed is @count@.
        required: false
        style: simple
        explode: true
        schema:
          type:
          - 'null'
          - array
          description: Additional information related to the user. Value allowed is @count@.
          items:
            type:
            - string
            - 'null'
            enum:
            - count
            maxLength: 100
            minLength: 0
          uniqueItems: true
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/getUsersResponse'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '500':
          $ref: ./Common.json#/components/responses/internalErrorResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
        - Desk.settings.READ
        - Desk.basic.READ
        - Desk.search.READ
      x-audience:
      - external-public
  /api/v1/users/{userId}/labels/assign:
    post:
      tags:
      - User
      summary: Assign Labels To User
      description: 'This API assigns the labels you specify to a particular user. '
      operationId: assignLabelsToUser
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      requestBody:
        $ref: '#/components/requestBodies/userLabelInputJson'
      responses:
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '200':
          $ref: '#/components/responses/massActionListViewResponse'
      security:
      - iam-oauth2-schema:
        - Desk.contacts.UPDATE
        - Desk.settings.UPDATE
      x-audience:
      - external-public
  /api/v1/users/{userId}/groups:
    get:
      tags:
      - User
      summary: Get User Groups
      description: This API lists a particular number of user groups in a help center, based on the limit defined.
      operationId: getUserGroups
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/userGroupJson'
        '422':
          $ref: ./Common.json#/components/responses/invalidDataErrorResponse
        '500':
          $ref: ./Common.json#/components/responses/internalErrorResponse
        '403':
          $ref: ./Common.json#/components/responses/forbiddenErrorResponse
      security:
      - iam-oauth2-schema:
        - Desk.contacts.READ
        - Desk.settings.READ
      x-audience:
      - external-public
components:
  responses:
    getUsersResponse:
      description: getUsersResponse template definitions
      content:
        application/json:
          schema:
            allOf:
            - type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      count:
                        type:
                        - string
                        - 'null'
                        - integer
                        format: int32
                        pattern: ([0-9]+)
            - oneOf:
              - type:
                - 'null'
                - object
                additionalProperties: false
                properties:
                  data:
                    $ref: ./User.json#/components/schemas/data
                required:
                - data
              - additionalProperties: false
                allOf:
                - $ref: ./User.json#/components/schemas/userListViewJson
                - type:
                  - 'null'
                  - object
                  properties:
                    count:
                      type:
                      - string
                      - 'null'
                      - integer
                      format: int32
                      pattern: ([0-9]+)
                  required:
                  - count
          examples:
            Valid responses Definitions:
              value:
                data:
                - lastAccessedTime: '2021-06-11T06:21:32.000Z'
                  photoURL: https://desk.zoho.com/portal/api/portalUser/17883000000094001/photo
                  emailAddress: carol@zylker.com
                  name: Developer
                  id: '310975130121'
                  label:
                    preferences:
                      shape: RECTANGLE
                      bgColor: '#39B54A'
                      textColor: '#FFFFFF'
                    name: Lock Label
                    id: '24073000002823026'
                    logoUrl: null
                  type: ENDUSER
                  status: ACTIVE
                count: '1'
    userLabelJson:
      description: userLabelJson template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              data:
                $ref: ./User.json#/components/schemas/userLabelJsonObj
            required:
            - data
          examples:
            Valid responses Definitions:
              value:
                data:
                - preferences:
                    shape: ROUNDED
                    bgColor: '#5787E0'
                    textColor: '#FFFFFF'
                  isPrimary: false
                  name: Prime Customer
                  id: '24073000002958013'
                  helpCenterId: '24073000002886005'
                  logoUrl: null
                  assignedTime: '2020-04-06T05:55:13.000Z'
                - preferences:
                    shape: RECTANGLE
                    bgColor: '#39B54A'
                    textColor: '#FFFFFF'
                  isPrimary: false
                  name: Zoho One
                  id: '24073000002958023'
                  helpCenterId: '24073000002886005'
                  logoUrl: null
                  assignedTime: '2020-04-06T05:55:13.000Z'
                - preferences:
                    shape: RECTANGLE
                    bgColor: '#CE6785'
                    textColor: '#FFFFFF'
                  isPrimary: false
                  name: MVP
                  id: '24073000002958029'
                  helpCenterId: '24073000002886005'
                  logoUrl: null
                  assignedTime: '2020-04-06T05:55:13.000Z'
    massActionListViewResponse:
      description: massActionListViewResponse template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              results:
                $ref: ./User.json#/components/schemas/massActionJsonArray
            required:
            - results
          examples:
            Valid responses Definitions:
              value:
                results:
                - success: true
                  id: '24073000002958013'
                  errors: null
                - success: true
                  id: '24073000002958023'
                  errors: null
                - success: false
                  id: '24073000002152013'
                  errors:
                    errorCode: FORBIDDEN
                    httpCode: 403
                    error: Restricted
    userDetailViewJson:
      description: userDetailViewJson template definitions
      content:
        application/json:
          schema:
            additionalProperties: false
            allOf:
            - $ref: ./User.json#/components/schemas/userDefaultJson
            - type:
              - 'null'
              - object
              properties:
                lastAccessedTime:
                  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))
                contactId:
                  type:
                  - string
                  - 'null'
                  - integer
                  format: int64
                  pattern: ([0-9]+)
                userType:
                  type:
                  - string
                  - 'null'
                  enum:
                  - ENDUSER
                  - SUPPORTREP
                  maxLength: 100
                  minLength: 0
                label:
                  $ref: ./Label.json#/components/schemas/labelMetaResponse
                email:
                  $ref: ./User.json#/components/schemas/userEmailObjArray
                status:
                  type:
                  - string
                  - 'null'
                  enum:
                  - ACTIVE
                  - DISABLED
                  - DELETED
                  maxLength: 100
                  minLength: 0
              required:
              - contactId
              - email
              - label
              - lastAccessedTime
              - status
              - userType
          examples:
            Valid responses Definitions:
              value:
                lastAccessedTime: '2021-06-11T06:21:32.000Z'
                photoURL: https://desk.zoho.com/portal/api/portalUser/17883000000094001/photo
                contactId: '3313135931139'
                name: Developer
                id: '310975130121'
                label:
                  preferences:
                    shape: RECTANGLE
                    bgColor: '#39B54A'
                    textColor: '#FFFFFF'
                  name: Lock Label
                  id: '24073000002823026'
                  logoUrl: null
                type: ENDUSER
                email:
                - emailAddress: zylcare@zylker.com
                  isVerified: 'false'
                  isPrimary: 'true'
                status: ACTIVE
    userGroupJson:
      description: userGroupJson template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              data:
                $ref: ./User.json#/components/schemas/userGroupJsonObj
            required:
            - data
          examples:
            Valid responses Definitions:
              value:
                data:
                - addedTime: '2020-04-06T04:50:50.000Z'
                  name: Zoho CRM Partners
                  id: '24073000002957057'
                  helpCenterId: '24073000002733221'
                  logoUrl: null
                  status: ACTIVE
                - addedTime: '2020-04-06T04:50:30.000Z'
                  name: Zoho Desk Partners
                  id: '24073000002957051'
                  helpCenterId: '24073000002733221'
                  logoUrl: https://desk.zoho.com/portal/api/publicImages/24073000002959001?portalId=b363e6f8e029247a38a55e49806bf1f683801f9cd92870bf7cc50d48844902f0
                  status: ACTIVE
                - addedTime: '2020-04-06T04:50:14.000Z'
                  name: Zoho One Prime Customers
                  id: '24073000002957045'
                  helpCenterId: '24073000002733221'
                  logoUrl: null
                  status: ACTIVE
  requestBodies:
    userLabelInputJson:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              labels:
                $ref: ./User.json#/components/schemas/userLabelInputJsonArr
            required:
            - labels
          examples:
            Valid requestBody Definitions:
              value:
                labels:
                - isPrimary: 'false'
                  id: '24073000002958013'
                - isPrimary: 'true'
                  id: '24073000002152013'
                - isPrimary: 'false'
                  id: '24073000002958023'
    updateUserJson:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              email:
                type:
                - 'null'
                - array
                items:
                  type:
                  - 'null'
                  - object
                  additionalProperties: false
                  maxProperties: 2
                  minProperties: 2
                  properties:
                    emailAddress:
                      type:
                      - string
                      - 'null'
                      maxLength: 100
                      minLength: 0
                      pattern: ^[a-zA-Z0-9\_]([a-zA-Z0-9\_\+\-\.\'&]*)@(?=.{4,256}$)(([a-zA-Z0-9]+)(([\-\_]*[a-zA-Z0-9])*)[\.])+[a-zA-Z]{2,22}$
                    isPrimary:
                      type:
                      - boolean
                      - 'null'
                  required:
                  - emailAddress
                  - isPrimary
                maxItems: 1
                minItems: 1
                uniqueItems: false
              status:
                type:
                - string
                - 'null'
                description: Activation status of the user. Values supported are @ACTIVE@ and @DISABLED@.
                enum:
                - ACTIVE
                - DISABLED
                - DELETED
                maxLength: 100
                minLength: 0
          examples:
            Valid requestBody Definitions:
              value:
                email:
                - emailAddress: zylcare@zylker.com
                  isPrimary: 'true'
                status: ACTIVE
    anonymizeInpJson:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              anonymizedName:
                type:
                - string
                - 'null'
                description: Display name of the user in tickets and community topics after anonymization
                maxLength: 100
                minLength: 0
          examples:
            Valid requestBody Definitions:
              value:
                anonymizedName: Guest User 001
    userGroupInputJson:
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              groups:
                $ref: ./User.json#/components/schemas/userGroupInputJsonArr
            required:
            - groups
          examples:
            Valid requestBody Definitions:
              value:
                groups:
                - id: '24073000002723212'
                - id: '24073000002732252'
                - id: '24073000002957051'
                - id: '24073000002793019'
  parameters:
    userId:
      name: userId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int64
        pattern: ([0-9]+)
  securitySchemes:
    iam-oauth2-schema:
      $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema
x-entity: Helpcenter