Zoho CRM Users API

openapi: 3.2.0
info:
  title: Zoho Crm Users API
  version: '1.0'
  description: 'Operations tagged Users across 4 of this provider''s published API definitions: zoho-crm-user-groups-openapi.json, zoho-crm-users-openapi.json, zoho-crm-users-territories-openapi.json, zoho-crm-users-transfer-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://zohoapis.{dc}/crm/{version}
  description: API Server URL
  variables:
    dc:
      enum:
      - com
      - eu
      - in
      - cn
      - au
      default: com
      description: API Server URL TLD
    version:
      default: v8
      description: API Version
tags:
- name: Users
paths:
  /users/{user}/actions/associated_groups:
    get:
      security:
      - iam-oauth2-schema:
        - ZohoCRM.settings.user_groups.READ
      summary: Get Associated Groups for User
      description: Get the list of user groups associated with the specified user.
      operationId: getAssociatedGroupsForUser
      parameters:
      - name: user
        in: path
        required: true
        description: The unique identifier of the user
        schema:
          type: string
          enum:
          - '3652397000000186017'
      - $ref: '#/components/parameters/Include'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Successfully retrieved the list of user groups associated with the specified user
          content:
            application/json:
              schema:
                description: Response containing list of associated user groups
                type: object
                additionalProperties: false
                properties:
                  user_groups:
                    description: Array of user groups
                    type: array
                    maxItems: 200
                    items:
                      description: User group details
                      type: object
                      additionalProperties: false
                      properties:
                        created_by:
                          description: User who created this group
                          type: object
                          additionalProperties: false
                          properties:
                            name:
                              description: Name of the creator
                              type: string
                              maxLength: 512
                            id:
                              description: ID of the creator
                              type: string
                              maxLength: 19
                          required:
                          - name
                          - id
                        modified_by:
                          description: User who last modified this group
                          oneOf:
                          - description: Modifier user information
                            type: object
                            additionalProperties: false
                            properties:
                              name:
                                description: Name of the modifier
                                type: string
                                maxLength: 512
                              id:
                                description: ID of the modifier
                                type: string
                                maxLength: 19
                            required:
                            - name
                            - id
                          - description: No modifier information available
                            type: 'null'
                        modified_time:
                          description: Last modification timestamp
                          oneOf:
                          - description: Timestamp in ISO 8601 format
                            type: string
                            format: date-time
                          - description: No modification time available
                            type: 'null'
                        created_time:
                          description: Creation timestamp
                          type: string
                          format: date-time
                        description:
                          description: Group description
                          oneOf:
                          - description: Group description text
                            type: string
                            maxLength: 250
                          - description: No description provided
                            type: 'null'
                        id:
                          description: Unique identifier for the group
                          type: string
                          maxLength: 19
                        name:
                          description: Name of the group
                          type: string
                          maxLength: 250
                        sources:
                          description: Array of sources for the user group
                          type: array
                          maxItems: 200
                          items:
                            description: Source details
                            type: object
                            additionalProperties: false
                            properties:
                              source:
                                description: Source information
                                type: object
                                additionalProperties: false
                                properties:
                                  name:
                                    description: Name of the source
                                    type: string
                                    maxLength: 250
                                  id:
                                    description: ID of the source
                                    type: string
                                    maxLength: 19
                                required:
                                - name
                                - id
                              type:
                                description: Type of the source
                                type: string
                                enum:
                                - users
                                - roles
                                - territories
                                - groups
                              subordinates:
                                description: Include subordinates flag
                                type: boolean
                              sub_territories:
                                description: Include sub-territories flag
                                type: boolean
                            required:
                            - source
                            - type
                        sources_count:
                          description: Count of sources by type
                          type: object
                          additionalProperties: false
                          properties:
                            territories:
                              description: Number of territories
                              type: integer
                              format: int32
                            roles:
                              description: Number of roles
                              type: integer
                              format: int32
                            groups:
                              description: Number of groups
                              type: integer
                              format: int32
                            users:
                              description: User count by status
                              type: object
                              additionalProperties: false
                              properties:
                                inactive:
                                  description: Number of inactive users
                                  type: integer
                                  format: int32
                                deleted:
                                  description: Number of deleted users
                                  type: integer
                                  format: int32
                                active:
                                  description: Number of active users
                                  type: integer
                                  format: int32
                              required:
                              - inactive
                              - deleted
                              - active
                      required:
                      - created_by
                      - modified_by
                      - modified_time
                      - created_time
                      - description
                      - id
                      - name
                  info:
                    type: object
                    description: Information about pagination
                    additionalProperties: false
                    properties:
                      per_page:
                        type: integer
                        format: int32
                        description: Number of records per page
                      count:
                        type: integer
                        format: int32
                        description: Number of records
                      page:
                        type: integer
                        format: int32
                        description: Current page number
                      more_records:
                        type: boolean
                        description: Indicates if there are more records available
                    required:
                    - per_page
                    - count
                    - page
                    - more_records
                required:
                - user_groups
                - info
        '400':
          description: Bad Request - Invalid input or request parameters
          content:
            application/json:
              schema:
                description: Error response for groups permission issue
                type: object
                additionalProperties: false
                properties:
                  code:
                    description: Error code
                    type: string
                    enum:
                    - INVALID_DATA
                  details:
                    description: Additional error details
                    type: object
                    additionalProperties: false
                    properties:
                      resource_path_index:
                        description: Index of the resource path with error
                        type: integer
                        format: int32
                    required:
                    - resource_path_index
                  message:
                    description: Human readable error message
                    type: string
                    maxLength: 500
                  status:
                    description: Error status
                    type: string
                    enum:
                    - error
                required:
                - code
                - details
                - message
                - status
        '404':
          description: Bad Request - Invalid input or request parameters
          content:
            application/json:
              schema:
                description: Error response for invalid URL pattern
                type: object
                additionalProperties: false
                properties:
                  code:
                    description: Error code
                    type: string
                    enum:
                    - INVALID_URL_PATTERN
                  details:
                    description: Additional error details
                    type: object
                    additionalProperties: false
                    properties: {}
                  message:
                    description: Human readable error message
                    type: string
                    maxLength: 500
                  status:
                    description: Error status
                    type: string
                    enum:
                    - error
                required:
                - code
                - details
                - message
                - status
      tags:
      - Users
    servers:
    - url: https://zohoapis.{dc}/crm/{version}
      description: API Server URL
      variables:
        dc:
          enum:
          - com
          - eu
          - in
          - cn
          - au
          default: com
          description: API Server URL TLD
        version:
          default: v8
          description: API Version
  /users:
    get:
      operationId: getUsers
      summary: Get users
      description: To get all users based on the provided parameters.
      security:
      - iam-oauth2-schema:
        - ZohoCRM.users.READ
      parameters:
      - $ref: '#/components/parameters/Type'
      - $ref: '#/components/parameters/Page_2'
      - $ref: '#/components/parameters/PerPage_2'
      - name: type__s
        in: query
        style: form
        explode: false
        description: type
        required: false
        schema:
          type: string
          enum:
          - Regular User
          - Sandbox Developer User
          - Team User
      responses:
        '200':
          description: All users details based on the provided parameters.
          content:
            application/json:
              schema:
                type: object
                description: List of users found based on the provided parameters.
                properties:
                  users:
                    maxItems: 200
                    type: array
                    description: List of users
                    items:
                      $ref: '#/components/schemas/UserDetails'
                  info:
                    $ref: '#/components/schemas/Info'
                additionalProperties: false
        '204':
          description: No users found based on the provided parameters.
      tags:
      - Users
    post:
      operationId: createUser
      description: Create a new user in the organization. API exposed to customers
      summary: Create User
      security:
      - iam-oauth2-schema:
        - ZohoCRM.users.CREATE
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: List of user details
              properties:
                users:
                  maxItems: 1
                  type: array
                  description: List of users
                  items:
                    $ref: '#/components/schemas/UserDetails'
              additionalProperties: false
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                description: Create User Success Response
                type: object
                properties:
                  users:
                    type: array
                    maxItems: 1
                    description: User creation success response
                    items:
                      description: User creation response object
                      type: object
                      properties:
                        code:
                          type: string
                          description: Response code
                          enum:
                          - SUCCESS
                        details:
                          type: object
                          description: Details of the created user
                          properties:
                            id:
                              type: string
                              description: ID of the created user
                              maxLength: 20
                          required:
                          - id
                          additionalProperties: false
                        message:
                          type: string
                          description: Response message
                          enum:
                          - User added
                        status:
                          type: string
                          description: Response status
                          enum:
                          - success
                      additionalProperties: false
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: Create User Bad Request Response
                type: object
                properties:
                  users:
                    type: array
                    maxItems: 1
                    description: User creation error response
                    items:
                      description: User creation error response object
                      type: object
                      properties:
                        code:
                          type: string
                          description: Error code
                          enum:
                          - INVALID_DATA
                          - DEPENDENT_FIELD_MISSING
                          - UNAPPROVABLE
                          - NOT_ALLOWED
                          - NOT_SUPPORTED
                          - MANDATORY_NOT_FOUND
                          - LICENSE_LIMIT_EXCEEDED
                          - DUPLICATE_DATA
                          - INVALID_REQUEST
                          - FEATURE_NOT_ENABLED
                          - REQUIRED_DATA_NOT_FOUND
                          - MAPPING_MISMATCH
                        details:
                          type: object
                          description: Details about the error
                          properties:
                            api_name:
                              type: string
                              description: API name of the field related to the error
                              maxLength: 100
                            json_path:
                              type: string
                              description: JSON path of the field related to the error
                              maxLength: 200
                            maximum_length:
                              type: integer
                              description: Maximum length allowed
                              format: int32
                            expected_data_type:
                              type: string
                              description: Expected data type
                              maxLength: 100
                            dependee:
                              type: object
                              description: Details of the dependee field
                              properties:
                                api_name:
                                  type: string
                                  description: API name of the dependee field
                                  maxLength: 100
                                json_path:
                                  type: string
                                  description: JSON path of the dependee field
                                  maxLength: 200
                              additionalProperties: false
                            resource_path_index:
                              type: integer
                              description: Index of the resource path in case of array
                              format: int32
                          additionalProperties: true
                        message:
                          type: string
                          description: Error message
                          enum:
                          - invalid data
                          - INVALID_DATA
                          - Give a proper time zone value
                          - Need shift_effective_from property to update users.
                          - Cannot add user for ZohoOne account from CRM. Kindly add user through ZohoOne
                          - Cannot add user for CRMPlus account from CRM. Kindly add user through CRMPlus
                          - ReportingTo Feature is not enabled
                          - You cannot create user in a sandbox org
                          - type__s is cannot be updated by api
                          - Company Name is required
                          - Support user cannot be added
                          - Unclosed Script tags found in signature
                          - Request exceeds your license limit. Need to upgrade in order to add a user
                          - Request exceeds your license limit. Need to upgrade in order to add a team user
                          - Failed to add user since same email id is already present
                          - User cannot be added as the user has already reached the maximum invitation limit
                          - Invalid current shift id
                          - Invalid next shift id
                          - This email address is already registered with another datacenter and cannot be registered with this account's data centre US
                          - Invalid Email Id. Please choose a different email id
                          - Email Id should not contain @zoho.com. Please choose a different email id
                          - Special Characters Found
                          - Pattern not matched
                          - current shift and next shift should not be same
                          - Dependent Field value should not be null
                          - the required current shift id value is not found
                          - Create operation cannot be performed for $next_shift and $shift_effective_from fields
                          - Create operation cannot be performed for $shift_effective_from field
                          - Create operation cannot be performed for $next_shift field
                          - Shift effective from date should be greater than Current Shift date
                          - Please update the current shift to update next shift
                          - the id given seems to be already deleted
                          - the number separator and decimal separator values should not be same
                          - Invalid data. Valid values are Comma/Period/Space (Not case-sensitive)
                          - Invalid data. Valid values are Comma/Period (Not case-sensitive)
                          - Created by & Modified by fields cannot be updated by api
                          - System user cannot be added
                          - Cannot update the sort_order_preference__s of another User
                          - Valid date format should be given
                        status:
                          type: string
                          description: Response status
                          enum:
                          - error
                      additionalProperties: false
                additionalProperties: true
        '403':
          description: permission denied
          content:
            application/json:
              schema:
                description: Permission Denied Response
                type: object
                properties:
                  code:
                    type: string
                    description: Error code
                    enum:
                    - NO_PERMISSION
                    - PERMISSION_DENIED
                  details:
                    type: object
                    description: Details about the error
                    properties:
                      permissions:
                        description: List of missing permissions
                        maxItems: 1
                        type: array
                        items:
                          type: string
                          description: Missing permission
                          enum:
                          - Crm_Implied_Manage_Users
                    additionalProperties: false
                  message:
                    description: Error message
                    type: string
                    enum:
                    - permission denied
                  status:
                    type: string
                    description: Response status
                    enum:
                    - error
                additionalProperties: false
      tags:
      - Users
    put:
      operationId: updateUser
      description: Update multiple users. API exposed to customers
      summary: Update User
      security:
      - iam-oauth2-schema:
        - ZohoCRM.users.UPDATE
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: List of user details
              properties:
                users:
                  maxItems: 10
                  type: array
                  description: List of users
                  items:
                    $ref: '#/components/schemas/UserDetails'
              additionalProperties: false
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                description: Update User Success Response
                type: object
                properties:
                  users:
                    type: array
                    maxItems: 10
                    description: User update success response
                    items:
                      description: User update response object
                      type: object
                      properties:
                        code:
                          type: string
                          description: Response code
                          enum:
                          - SUCCESS
                        details:
                          type: object
                          description: Details of the updated user
                          properties:
                            id:
                              type: string
                              description: ID of the updated user
                              maxLength: 20
                          required:
                          - id
                          additionalProperties: false
                        message:
                          type: string
                          description: Response message
                          enum:
                          - User updated
                        status:
                          type: string
                          description: Response status
                          enum:
                          - success
                      additionalProperties: false
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: Update User Bad Request Response
                type: object
                properties:
                  users:
                    type: array
                    maxItems: 1
                    description: User update error response
                    items:
                      description: User update error response object
                      type: object
                      required:
                      - code
                      - message
                      - status
                      properties:
                        code:
                          type: string
                          description: Error code
                          enum:
                          - INVALID_DATA
                          - NOT_ALLOWED
                          - MANDATORY_NOT_FOUND
                          - CANNOT_UPDATE_DELETED_USER
                          - EMAIL_UPDATE_NOT_ALOWED
                          - INVALID_REQUEST
                          - DUPLICATE_DATA
                          - ID_ALREADY_DEACTIVATED
                          - NOT_SUPPORTED
                          - UNAPPROVABLE
                          - LICENSE_LIMIT_EXCEEDED
                          - AUTHORIZATION_FAILED
                          - FEATURE_NOT_AVAILABLE
                          - CONFLICTING_DATA_FOUND
                          - REQUIRED_DATA_NOT_FOUND
                          - ID_ALREADY_ACTIVE
                          - MAPPING_MISMATCH
                          - FEATURE_NOT_ENABLED
                        details:
                          type: object
                          description: Details about the error
                          properties:
                            api_name:
                              type: string
                              description: API name of the field related to the error
                              maxLength: 100
                            json_path:
                              type: string
                              description: JSON path of the field related to the error
                              maxLength: 200
                            maximum_length:
                              type: integer
                              description: Maximum length allowed
                              format: int32
                            expected_data_type:
                              type: string
                              description: Expected data type
                              maxLength: 100
                            dependee:
                              type: object
                              description: Details of the dependee field
                              properties:
                                api_name:
                                  type: string
                                  description: API name of the dependee field
                                  maxLength: 100
                                json_path:
                                  type: string
                                  description: JSON path of the dependee field
                                  maxLength: 200
                              additionalProperties: false
                            resource_path_index:
                              type: integer
                              description: Index of the resource path in case of array
                              format: int32
                          additionalProperties: true
                        message:
                          type: string
                          description: Error message
                          enum:
                          - invalid data
                          - required field not found
                          - the id given seems to be invalid
                          - the user must be updated with new eligible reporting manager because of changing user role
                          - the user must be updated with new eligible reporting manager and the subordinates  who are going to  report to a user in a role below them, because of new role change are need to transfer to new eligible reporting manager
                          - Need shift_effective_from property to update users.
                          - Special Characters Found
                          - Pattern not matched
                          - Cannot add user for ZohoOne account from CRM. Kindly add user through ZohoOne
                          - Cannot add user for CRMPlus account from CRM. Kindly add user through CRMPlus
                          - You cannot update user in a sandbox org
                          - type__s is cannot be updated by api
                          - Company Name is required
                          - Support user cannot be added
                          - Unclosed Script tags found in signature
                          - You are trying to activate more mail addon which exceeds your license limit. If you want to activate mail addon for additional users, please upgrade your license
         

# --- truncated at 32 KB (158 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-users-api-openapi.yml