Zoho CRM Records API

openapi: 3.2.0
info:
  title: Zoho Crm Records API
  version: '8.0'
  description: 'Operations tagged Records across 2 of this provider''s published API definitions: zoho-crm-record-count-openapi.json, zoho-crm-record-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: The domain corresponding to your Zoho CRM data center (e.g., www.zohoapis.com, www.zohoapis.eu).
    version:
      enum:
      - v8
      default: v8
      description: API version
tags:
- name: Records
paths:
  /{moduleApiName}/actions/count:
    get:
      tags:
      - Records
      summary: Get Record Count in a Module
      description: 'Fetches the total number of records in a specified module.

        The count can be filtered using `cvid` (Custom View ID) or one of the search parameters (`criteria`, `phone`, `email`, `word`).


        **Important Constraint (Zoho Documentation):**

        You can only include **either** `cvid` **or** one of the search parameters (`criteria`, `phone`, `email`, `word`) in a single request. Combining `cvid` with any search parameter will result in an `AMBIGUITY_DURING_PROCESSING` error (HTTP 400).'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.ALL
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Leads.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Contacts.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Accounts.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Deals.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Tasks.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Events.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Calls.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Products.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Vendors.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Campaigns.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Cases.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Solutions.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.pricebooks.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.Quotes.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.salesorders.READ
        - ZohoSearch.securesearch.READ
      - iam-oauth2-schema:
        - ZohoCRM.modules.purchaseorders.READ
        - ZohoSearch.securesearch.READ
      operationId: getCount
      parameters:
      - $ref: '#/components/parameters/ModuleApiName'
      - $ref: '#/components/parameters/Email'
      - $ref: '#/components/parameters/Phone'
      - $ref: '#/components/parameters/Word'
      - $ref: '#/components/parameters/Cvid'
      - $ref: '#/components/parameters/Criteria'
      - $ref: '#/components/parameters/Converted'
      - $ref: '#/components/parameters/Approved'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Type'
      responses:
        '200':
          description: Successful response containing the total record count.
          content:
            application/json:
              schema:
                type: object
                description: Response containing the total number of records matching the provided filters (if any).
                additionalProperties: false
                properties:
                  count:
                    type: integer
                    format: int32
                    description: Total number of matching records.
                required:
                - count
        '400':
          description: Bad Request - invalid module name, unsupported module, or ambiguous use of parameters.
          content:
            application/json:
              schema:
                description: Union schema for possible 400 Bad Request error responses for GET /{module_api_name}/actions/count.
                oneOf:
                - type: object
                  description: Invalid request error response
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating invalid request
                      enum:
                      - INVALID_REQUEST
                    message:
                      type: string
                      description: Human-readable error message
                      maxLength: 1000
                      const: unable to process your request. please verify whether you have entered proper method name, parameter and parameter values.
                    details:
                      type: object
                      description: Additional error details
                      additionalProperties: false
                  required:
                  - status
                  - code
                  - message
                - type: object
                  description: Invalid request error response
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating invalid request
                      enum:
                      - FIELD_TYPE_UNAVAILABLE
                    message:
                      type: string
                      description: Human-readable error message
                      maxLength: 1000
                      enum:
                      - this data type is not found in this module
                    details:
                      type: object
                      description: Additional error details
                      additionalProperties: false
                  required:
                  - status
                  - code
                  - message
                - type: object
                  description: Operation not supported error response
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      const: error
                    code:
                      type: string
                      description: Error code indicating unsupported operation
                      const: NOT_SUPPORTED
                    message:
                      type: string
                      description: Human-readable error message
                      maxLength: 1000
                      enum:
                      - The module does not support this operation
                      - module not suppoted for search
                      - the given module is not supported for count
                    details:
                      type: object
                      description: Additional error details including module information
                      additionalProperties: false
                      properties:
                        module:
                          type: string
                          description: The module that does not support this operation
                          maxLength: 100
                  required:
                  - status
                  - code
                  - message
                  - details
                - type: object
                  description: Missing required parameter error response
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating missing parameters
                      enum:
                      - EXPECTED_PARAM_MISSING
                    message:
                      type: string
                      description: Human-readable error message
                      maxLength: 1000
                    details:
                      type: object
                      description: Additional error details including missing parameter names
                      additionalProperties: false
                      properties:
                        param_names:
                          type: array
                          description: List of missing parameter names
                          maxItems: 50
                          items:
                            type: string
                            description: Parameter name
                            maxLength: 100
                            enum:
                            - criteria
                            - email
                            - phone
                            - word
                      required:
                      - param_names
                  required:
                  - status
                  - code
                  - message
                  - details
                - type: object
                  description: Invalid module error response
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating invalid module
                      enum:
                      - INVALID_MODULE
                    message:
                      type: string
                      description: Human-readable error message
                      maxLength: 1000
                    details:
                      type: object
                      description: Additional error details including resource path information
                      additionalProperties: false
                      properties:
                        resource_path_index:
                          type: integer
                          description: Index of the invalid resource path segment
                          format: int32
                  required:
                  - status
                  - code
                  - message
                  - details
                - type: object
                  description: Invalid query error response with various detail formats
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating invalid query
                      enum:
                      - INVALID_QUERY
                    message:
                      type: string
                      description: Human-readable error message describing the query issue
                      enum:
                      - Cannot use the restricted field.
                      - Invalid query formed
                      - invalid value for search
                      - the field is not available for search
                      - Please check the value of the field
                      - special characters are not allowed
                      - invalid operator found
                      - no_masking_permission
                      - More than one wildcard(*) not allowed in a searchword
                    details:
                      oneOf:
                      - type: object
                        description: Invalid Operator passed for datatype
                        additionalProperties: false
                        properties:
                          operator:
                            type: string
                            description: The invalid operator used in the query
                            maxLength: 50
                        required:
                        - operator
                        - api_name
                      - type: object
                        description: Data type mismatch error details
                        additionalProperties: false
                        properties:
                          expected_data_type:
                            type: string
                            description: The expected data type for the field
                            maxLength: 100
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                        required:
                        - expected_data_type
                        - reason
                        - api_name
                      - type: object
                        description: Data type mismatch error details
                        additionalProperties: false
                        properties:
                          expected_data_type:
                            type: string
                            description: The expected data type for the field
                            maxLength: 100
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                          value:
                            type: string
                            description: The invalid value provided in the query
                            maxLength: 500
                        required:
                        - expected_data_type
                        - reason
                        - api_name
                        - value
                      - type: object
                        description: Invalid operator error details
                        additionalProperties: false
                        properties:
                          operator:
                            type: string
                            description: The invalid operator used in the query
                            maxLength: 50
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                        required:
                        - operator
                        - reason
                        - api_name
                      - type: object
                        description: General query error details
                        additionalProperties: false
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                          details:
                            type: string
                            description: Additional details about the error, only Zoho Search team
                            maxLength: 1000
                        required:
                        - reason
                        - api_name
                      - type: object
                        description: Invalid value error details
                        additionalProperties: false
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                          value:
                            type: string
                            description: The invalid value provided in the query
                            maxLength: 500
                        required:
                        - reason
                        - api_name
                        - value
                      - type: object
                        description: Invalid value error details
                        additionalProperties: false
                        properties:
                          param_name:
                            type: string
                            description: Name of the parameter causing the error
                            maxLength: 500
                            enum:
                            - email
                            - phone
                            - word
                        required:
                        - param_name
                      - type: object
                        description: Invalid value error details
                        additionalProperties: false
                  required:
                  - status
                  - code
                  - message
                  - details
                - type: object
                  description: Invalid query error response with various detail formats
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating invalid query
                      enum:
                      - INVALID_DATA
                    message:
                      type: string
                      description: Human-readable error message describing the query issue
                      enum:
                      - Cannot use the restricted field.
                      - Invalid query formed
                      - invalid value for search
                      - the field is not available for search
                      - Please check the value of the field
                      - special characters are not allowed
                      - invalid operator found
                      - no_masking_permission
                      - invalid data
                      - More than one wildcard(*) not allowed in a searchword
                      - provide atleast 2 letters for search
                    details:
                      oneOf:
                      - type: object
                        description: Data type mismatch error details
                        additionalProperties: false
                        properties:
                          expected_data_type:
                            type: string
                            description: The expected data type for the field
                            maxLength: 100
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                        required:
                        - expected_data_type
                        - reason
                        - api_name
                      - type: object
                        description: Invalid operator error details
                        additionalProperties: false
                        properties:
                          operator:
                            type: string
                            description: The invalid operator used in the query
                            maxLength: 50
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                        required:
                        - operator
                        - reason
                        - api_name
                      - type: object
                        description: General query error details
                        additionalProperties: false
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                          details:
                            type: string
                            description: Additional details about the error, only Zoho Search team
                            maxLength: 1000
                        required:
                        - reason
                        - api_name
                      - type: object
                        description: Invalid value error details
                        additionalProperties: false
                        properties:
                          reason:
                            type: string
                            description: Detailed reason for the error
                            maxLength: 500
                          value:
                            type: string
                            description: The invalid value provided in the query
                            maxLength: 500
                        required:
                        - reason
                        - api_name
                        - value
                      - type: object
                        description: Invalid value error details
                        additionalProperties: false
                        properties:
                          param_name:
                            type: string
                            description: Name of the parameter causing the error
                            maxLength: 500
                        required:
                        - param_name
                      - type: object
                        description: Invalid value error details
                        additionalProperties: false
                  required:
                  - status
                  - code
                  - message
                  - details
                - type: object
                  description: Invalid query error response for IN operator violations
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating invalid query
                      enum:
                      - INVALID_QUERY
                    message:
                      type: string
                      description: Human-readable error message describing the query issue
                      enum:
                      - Only 100 values are allowed in "IN" criteria
                      - Invalid query formed
                    details:
                      type: object
                      description: Additional error details including field information
                      additionalProperties: false
                      properties:
                        param_name:
                          type: string
                          description: Name of the parameter causing the error
                          maxLength: 100
                      required:
                      - api_name
                  required:
                  - status
                  - code
                  - message
                  - details
                - type: object
                  description: Limit reached error response when maximum record iteration exceeded
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating limit reached
                      enum:
                      - LIMIT_REACHED
                    message:
                      type: string
                      description: Human-readable error message
                      enum:
                      - maximum response iteration limit reached
                    details:
                      type: object
                      description: Additional error details including the limit value
                      additionalProperties: false
                      properties:
                        limit:
                          type: string
                          description: Maximum number of records allowed
                          enum:
                          - '2000'
                      required:
                      - limit
                  required:
                  - status
                  - code
                  - message
                  - details
                - type: object
                  description: Criteria limit exceeded error response
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      description: Error status indicator
                      enum:
                      - error
                    code:
                      type: string
                      description: Error code indicating criteria limit exceeded
                      enum:
                      - CRITERIA_LIMIT_EXCEEDED
                    message:
                      type: string
                      description: Human-readable error message
                      enum:
                      - no of criterium that can be given exceed the limit 15
                    details:
                      type: object
                      description: Additional error details
                      additionalProperties: false
                  required:
                  - status
                  - code
                  - message
                  - details
                - type: object
                  description: Ambiguity during processing error response
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      enum:
                      - error
                      description: Indicates the response is an error.
                    code:
                      type: string
                      enum:
                      - AMBIGUITY_DURING_PROCESSING
                      description: Error code representing ambiguity during request processing.
                    message:
                      type: string
                      description: Detailed message describing the ambiguity in the request.
                      maxLength: 512
                      enum:
                      - Please use either Cvid or Search Params. Combination of both the params is not allowed
                    details:
                      type: object
                      description: Additional details about the ambiguity.
                      additionalProperties: false
                      properties:
                        ambiguity_due_to:
                          type: array
                          description: List of parameters causing ambiguity.
                          maxItems: 2
                          items:
                            type: object
                            additionalProperties: false
                            description: Parameter causing ambiguity.
                            properties:
                              param_name:
                                type: string
                                description: Name of the parameter causing ambiguity.
                                maxLength: 100
                            required:
                            - param_name
                - description: Error response when the requested operation or module is not supported.
                  type: object
                  additionalProperties: false
                  properties:
                    status:
                      type: string
                      enum:
                      - error
                      description: Indicates the response is an error.
                    code:
                      type: string
                      enum:
                      - API_NOT_SUPPORTED
                      description: Error code representing unsupported operation or module.
                    message:
                      type: string
                      description: Detailed message describing why the request is not supported.
                      maxLength: 512
                      enum:
                      - api not supported in this version
                    details:
                      type: object
                      description: Additional details including the unsupported module name.
                      additionalProperties: false
                      properties:
                        supported_version:
                          type: string
                          description: The API version that supports this operation.
                          maxLength: 100
                          enum:
                          - v2.1
                  required:
                  - status
                  - code
                  - message
        '401':
          description: Unauthorized (e.g., OAUTH_SCOPE_MISMATCH).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://zohoapis.{dc}/crm/{version}
      description: API Server URL
      variables:
        dc:
          enum:
          - com
          - eu
          - in
          - cn
          - au
          default: com
          description: The domain corresponding to your Zoho CRM data center (e.g., www.zohoapis.com, www.zohoapis.eu).
        version:
          enum:
          - v8
          default: v8
          description: API version
  /{module}:
    get:
      operationId: getRecords
      description: To get the list of available records from a module
      summary: Get Records for a specific module
      parameters:
      - $ref: '#/components/parameters/Module'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/TerritoryId'
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/Cvid_2'
      - $ref: '#/components/parameters/PerPage_2'
      - $ref: '#/components/parameters/Page_2'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/SortOrder'
      - $ref: '#/components/parameters/SortBy'
      - $ref: '#/components/parameters/Converted_2'
      - $ref: '#/components/parameters/IncludeChild'
      responses:
        '200':
          description: Successful response containing the list of records for the specified module
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordGETSucessResponse'
        '204':
          description: No Content - The request was successful, but no records found.
        '400':
          description: Bad Request - The request could not be processed due to invalid input, missing mandatory parameters
          content:
            application/json:
              schema:
                $ref: '#/components

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