openapi: 3.0.0
info:
  title: Userfields
  description: |
    Userfields are pieces of information associated with a user in Zoho Cliq. They store additional details that help manage and organize users within a company. Most default userfields in Cliq are customizable, and organizations can create custom userfields to address specific needs. <br><br>Using the Userfields APIs, developers can retrieve, add, update, and manage both default and custom userfields programmatically.
  contact: {}
  version: 1.0.0
externalDocs:
  description: Find out more about Zoho Cliq APIs V2
  url: https://www.zoho.com/cliq/help/restapi/v2/
servers:
  - url: https://cliq.zoho.com/api/v2
    description: Zoho Cliq US DC
tags:
  - name: userfields
    description: Userfields Module
paths:
  /userfields:
    get:
      summary: Get all userfields
      operationId: Get all userfields
      description: |
        Use this API to get the details of all userfields.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserfieldListResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Users.READ
      tags:
        - userfields
    post:
      summary: Add a userfield
      operationId: Add a userfield
      description: |
        Use this API to create a new custom userfield.
        <b>Note:</b> You can also encrypt the userfield if it contains sensitive data.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserfieldCreateRequest'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserfieldCreateResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.UserFields.CREATE
      tags:
        - userfields
  /userfields/{FIELD_ID}:
    get:
      summary: Retrieve a particular userfield
      operationId: Retrieve a particular userfield
      description: |
        Use this API to get the details of a particular userfield.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: FIELD_ID
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the userfield for which detailed information needs to be retrieved To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#FIELD_ID">FIELD_ID</a> in the Glossary page.
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Retrieve-Userfield'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Users.READ
      tags:
        - userfields
    put:
      summary: Update a userfield
      operationId: Update a userfield
      description: |
        Use this API to update the details of a particular userfield.
        <br><br>
        <b>Note:</b> When updating the drop_down type userfields, the unique ID's of the options should be unique i.e, they should not be repetitive.
        If multiple options have the same unique ID they will be replaced with one.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: FIELD_ID
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the userfield which needs to be updated To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#FIELD_ID">FIELD_ID</a> in the Glossary page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserfieldUpdateRequest'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserfieldUpdateResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Userfields.UPDATE
      tags:
        - userfields
    delete:
      summary: Delete a userfield
      operationId: Delete a userfield
      description: |
        Use this API to delete a particular userfield.
        <br><br> 
        <p>
          <b>Threshold limit</b>: 10 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: FIELD_ID
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the userfield which needs to be deleted To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#FIELD_ID">FIELD_ID</a> in the Glossary page.
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/no-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Userfields.DELETE
      tags:
        - userfields
components:
  schemas:
    no-response:
      type: object
      description: Generic response when no content is returned.
      properties:
        Response Code:
          type: string
          description: HTTP response code indicating no response.
          example: 204 No response
    UserfieldListResponse:
      type: object
      description: Response containing the list of userfields in the organization.
      properties:
        url:
          type: string
          description: API endpoint for fetching userfields.
          example: /api/v2/userfields
        list:
          type: array
          description: Array of userfield objects.
          items:
            type: object
            properties:
              system_defined:
                type: boolean
                description: Indicates if the userfield is system-defined.
              is_searchable:
                type: boolean
                description: Indicates if the field can be used in searches.
              unique_name:
                type: string
                description: Unique identifier for the userfield.
              name:
                type: string
                description: Display name of the userfield.
              id:
                type: string
                description: Unique ID of the userfield.
              creation_time:
                type: string
                format: date-time
                description: Timestamp when the userfield was created.
              last_modified_time:
                type: string
                format: date-time
                description: Timestamp when the userfield was last modified.
              mandatory:
                type: boolean
                description: Indicates if the field is mandatory for users.
              encrypted:
                type: boolean
                description: Indicates if the field is encrypted.
              edit_permission:
                type: boolean
                description: Indicates whether users can edit this field.
              organization_id:
                type: string
                description: ID of the organization that owns the field.
              enabled:
                type: boolean
                description: Indicates if the field is enabled.
              type:
                type: string
                description: Type of the userfield (text_field, date_picker, drop_down, etc.).
              label:
                type: string
                description: Label for the userfield.
              default_value:
                type: string
                description: Default value of the field.
          example:
            - system_defined: false
              is_searchable: false
              unique_name: description
              name: Description
              id: '1901318000003077001'
              creation_time: '2021-04-15T20:34:10-07:00'
              last_modified_time: '2021-08-03T21:39:06-07:00'
              mandatory: true
              encrypted: false
              edit_permission: false
              organization_id: '631836344'
              enabled: true
              type: text_field
              label: Description
              default_value: '-'
            - system_defined: true
              is_searchable: true
              unique_name: extension
              name: Extension
              id: '1901318000001264019'
              creation_time: '2019-02-03T23:08:33-08:00'
              last_modified_time: '2019-06-13T22:57:30-07:00'
              mandatory: false
              edit_permission: false
              organization_id: '631836344'
              enabled: true
              type: text_field
              label: Extension
            - system_defined: false
              is_searchable: false
              unique_name: dateofjoining
              name: Date of Joining
              id: '1901318000001602021'
              creation_time: '2019-06-13T22:58:00-07:00'
              last_modified_time: '2021-08-03T21:05:20-07:00'
              mandatory: false
              encrypted: false
              edit_permission: false
              organization_id: '631836344'
              enabled: true
              type: date_picker
              label: Date of Joining
              default_value: '-'
    UserfieldCreateRequest:
      type: object
      description: Request body to create a new userfield.
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 30
          description: Display name of the userfield.
          example: Vaccinated
        type:
          type: string
          description: Type of the userfield (text_field, drop_down, date_picker, etc.).
          example: drop_down
        mandatory:
          type: boolean
          description: Indicates if the field is mandatory for all users.
          example: true
        encrypted:
          type: boolean
          description: Indicates if the field should be encrypted.
          example: false
        edit_permission:
          type: boolean
          description: Indicates if users can edit this field.
          example: true
        options:
          type: array
          description: Required for drop_down type fields. List of selectable options.
          items:
            type: string
            description: An option available for selection in the drop_down field.
          example:
            - 'Yes'
            - 'No'
            - Prefer not to say
    UserfieldCreateResponse:
      type: object
      description: Response returned after creating a userfield.
      properties:
        url:
          type: string
          example: /api/v2/userfields
        data:
          type: object
          properties:
            system_defined:
              type: boolean
              example: false
            is_searchable:
              type: boolean
              example: false
            unique_name:
              type: string
              example: vaccinated
            name:
              type: string
              example: Vaccinated
            id:
              type: string
              example: '1901318000003603019'
            creation_time:
              type: string
              format: date-time
              example: '2021-11-30T21:47:14-08:00'
            last_modified_time:
              type: string
              format: date-time
              example: '2021-11-30T21:47:14-08:00'
            mandatory:
              type: boolean
              example: true
            encrypted:
              type: boolean
              example: false
            edit_permission:
              type: boolean
              example: true
            organization_id:
              type: string
              example: '631836344'
            enabled:
              type: boolean
              example: true
            type:
              type: string
              example: drop_down
            label:
              type: string
              example: Vaccinated
            options:
              type: array
              description: List of options for drop_down fields.
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: 'Yes'
                  id:
                    type: string
                    example: '1901318000003603021'
              example:
                - name: 'No'
                  id: '1901318000003603023'
                - name: 'Yes'
                  id: '1901318000003603021'
    Retrieve-Userfield:
      type: object
      description: Response for retrieving a single userfield by ID.
      properties:
        url:
          type: string
          example: /api/v2/userfields/1901318000001602017
        data:
          type: object
          properties:
            system_defined:
              type: boolean
              example: false
            is_searchable:
              type: boolean
              example: false
            unique_name:
              type: string
              example: workshift
            name:
              type: string
              example: Work Shift
            id:
              type: string
              example: '1901318000001602017'
            creation_time:
              type: string
              format: date-time
              example: '2019-06-13T22:57:01-07:00'
            last_modified_time:
              type: string
              format: date-time
              example: '2019-08-14T05:13:09-07:00'
            mandatory:
              type: boolean
              example: false
            encrypted:
              type: boolean
              example: false
            edit_permission:
              type: boolean
              example: false
            organization_id:
              type: string
              example: '631836344'
            enabled:
              type: boolean
              example: true
            type:
              type: string
              example: text_field
            label:
              type: string
              example: Work Shift
            default_value:
              type: string
              example: '-'
    UserfieldUpdateRequest:
      type: object
      description: Request body to update an existing userfield.
      properties:
        name:
          type: string
          maxLength: 30
          description: Display name of the userfield.
          example: Vaccinated
        mandatory:
          type: boolean
          description: Indicates if the field should be mandatory.
          example: true
        encrypted:
          type: boolean
          description: Indicates if the field should be encrypted.
          example: false
        edit_permission:
          type: boolean
          description: Indicates if users can edit the field.
          example: true
        options:
          type: array
          description: |
            If "drop_down" is selected as the type, the options for the drop_down must be specified using the options key. 
            Note that the previous options must also be included in the updated list, or they will be deleted.
          items:
            type: object
            properties:
              id:
                type: string
                description: ID of the option.
                example: '1901318000003603021'
              name:
                type: string
                description: Display name of the option.
                example: Yes I have been vaccinated
          example:
            - id: '1901318000003603021'
              name: Yes I have been vaccinated
            - id: '1901318000003603023'
              name: No I am yet to get vaccinated
    UserfieldUpdateResponse:
      type: object
      description: Response returned after updating a userfield.
      properties:
        url:
          type: string
          example: /api/v2/userfields/1901318000003603019
        data:
          type: object
          properties:
            system_defined:
              type: boolean
              example: false
            is_searchable:
              type: boolean
              example: false
            unique_name:
              type: string
              example: vaccinated
            name:
              type: string
              example: Vaccinated
            id:
              type: string
              example: '1901318000003603019'
            creation_time:
              type: string
              format: date-time
              example: '2021-11-30T21:47:14-08:00'
            last_modified_time:
              type: string
              format: date-time
              example: '2021-11-30T23:32:14-08:00'
            mandatory:
              type: boolean
              example: true
            encrypted:
              type: boolean
              example: false
            edit_permission:
              type: boolean
              example: false
            organization_id:
              type: string
              example: '631836344'
            enabled:
              type: boolean
              example: true
            type:
              type: string
              example: drop_down
            label:
              type: string
              example: Vaccinated
            default_value:
              type: string
              example: 'No'
            options:
              type: array
              description: Updated list of options for drop_down fields.
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: No I am yet to get vaccinated
                  id:
                    type: string
                    example: '1901318000003603023'
              example:
                - name: No I am yet to get vaccinated
                  id: '1901318000003603023'
                - name: Yes I have been vaccinated
                  id: '1901318000003603021'
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.Users.READ: Read Users
            ZohoCliq.UserFields.CREATE: Create new Users
            ZohoCliq.Userfields.UPDATE: Update Userfields
            ZohoCliq.Userfields.DELETE: Delete Userfields
