Zoho Zoho CRM Related Records API API

openapi: 3.1.0
info:
  title: Helpcenter Zoho CRM Related Records API API
  version: 1.0.0
tags:
- name: Zoho CRM Related Records API
paths:
  /{parentRecordModule}/{parentRecord}/{relatedList}:
    get:
      summary: List Related Records
      description: Retrieves a paginated list of records from a specific related list of a parent record in a CRM module. Supports filtering by fields and conditional requests using If-Modified-Since header.
      operationId: getRelatedRecords
      parameters:
      - $ref: '#/components/parameters/ParentRecordModule'
      - $ref: '#/components/parameters/ParentRecord'
      - $ref: '#/components/parameters/RelatedList'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/IfModifiedSince'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/IdsOptional'
      - $ref: '#/components/parameters/SortOrder'
      - $ref: '#/components/parameters/SortBy'
      - $ref: '#/components/parameters/Converted'
      responses:
        '200':
          description: Successfully retrieved related records with comprehensive pagination metadata and field data.
          content:
            application/json:
              schema:
                type: object
                description: Response containing related records data with pagination metadata
                additionalProperties: false
                required:
                - data
                - info
                properties:
                  data:
                    type: array
                    description: Array of related record objects with requested fields
                    maxItems: 200
                    items:
                      type: object
                      description: Individual related record with dynamic CRM fields
                      additionalProperties: true
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the related record
                          pattern: ^[0-9]+$
                          maxLength: 20
                        Created_Time:
                          type: string
                          description: Timestamp when the record was created
                          format: date-time
                        Modified_Time:
                          type: string
                          description: Timestamp when the record was last modified
                          format: date-time
                        Moved_To__s:
                          type: string
                          description: Stage value to which the record was moved (stage history / picklist movement).
                          maxLength: 255
                  info:
                    type: object
                    description: Pagination and response metadata
                    additionalProperties: false
                    required:
                    - page
                    - per_page
                    - count
                    - more_records
                    properties:
                      page:
                        type: integer
                        format: int32
                        description: Current page number
                        minimum: 1
                      per_page:
                        type: integer
                        format: int32
                        description: Number of records per page
                        minimum: 1
                        maximum: 200
                      count:
                        type: integer
                        format: int32
                        description: Number of records in current response
                        minimum: 0
                      more_records:
                        type: boolean
                        description: Indicates if more pages are available
                      next_page_token:
                        type:
                        - string
                        - 'null'
                        description: Token to retrieve the next page of results
                        maxLength: 500
                      page_token_expiry:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: Expiration timestamp for the page token
                      previous_page_token:
                        type:
                        - string
                        - 'null'
                        description: Token to retrieve the previous page of results
                        maxLength: 500
        '204':
          description: No related records found for the specified parent record
        '400':
          description: Bad Request - Various client errors
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/NotSupportedError'
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidRequestMethodError'
                - $ref: '#/components/schemas/AuthorizationFailedError'
                - $ref: '#/components/schemas/RequiredParamMissingError'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidTokenError'
                - $ref: '#/components/schemas/OAuthScopeMismatchError'
        '403':
          description: Permission denied to read related records
          content:
            application/json:
              schema:
                x-zs-$id: NoPermissionError
                $ref: '#/components/schemas/NoPermissionError'
        '404':
          description: Not Found - Parent record or related list does not exist
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RecordNotFoundError'
                - $ref: '#/components/schemas/InvalidUrlPatternError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                x-zs-$id: InternalError
                $ref: '#/components/schemas/InternalError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.READ
      tags:
      - Zoho CRM Related Records API
    put:
      summary: Update Related Records
      description: Updates multiple related records' specific properties in a specified related list.
      operationId: updateRelatedRecords
      parameters:
      - $ref: '#/components/parameters/ParentRecordModule'
      - $ref: '#/components/parameters/ParentRecord'
      - $ref: '#/components/parameters/RelatedList'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request payload for updating multiple related records
              additionalProperties: false
              required:
              - data
              properties:
                data:
                  type: array
                  description: Array of records to update with their IDs and field values
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    description: Individual record update with ID and fields to modify
                    additionalProperties: true
                    required:
                    - id
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the record to update
                        pattern: ^[0-9]+$
                        maxLength: 20
      responses:
        '200':
          description: Successfully updated related records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResponse'
        '207':
          description: Multi-Status - Bulk update processed with mixed results (some updated, some failed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResponse'
        '400':
          description: Bad Request - Various client errors
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/NotSupportedError'
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidRequestMethodError'
                - $ref: '#/components/schemas/AuthorizationFailedError'
                - $ref: '#/components/schemas/MandatoryNotFoundError'
                - $ref: '#/components/schemas/RelationNotFoundBulkError'
                - $ref: '#/components/schemas/MandatoryNotFoundBulkError'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidTokenError'
                - $ref: '#/components/schemas/OAuthScopeMismatchError'
        '403':
          description: Permission denied to read related records
          content:
            application/json:
              schema:
                x-zs-$id: NoPermissionError
                $ref: '#/components/schemas/NoPermissionError'
        '404':
          description: 'Not Found - INVALID_URL_PATTERN: Please check if the URL trying to access is a correct one. Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to request URL section above. (Or) the specified parent/related record does not exist.'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RecordNotFoundError'
                - $ref: '#/components/schemas/InvalidUrlPatternError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                x-zs-$id: InternalError
                $ref: '#/components/schemas/InternalError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.UPDATE
      tags:
      - Zoho CRM Related Records API
    delete:
      summary: Remove Related Records by IDs
      description: Removes relationships between a parent record and multiple records in a specified related list, identified by their IDs in the query parameter. This operation deletes only the relationship links, not the actual records themselves. The target records remain intact in their respective modules.
      operationId: delinkRelatedRecords
      parameters:
      - $ref: '#/components/parameters/ParentRecordModule'
      - $ref: '#/components/parameters/ParentRecord'
      - $ref: '#/components/parameters/RelatedList'
      - $ref: '#/components/parameters/Ids'
      responses:
        '200':
          description: Successfully delinked related records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResponse'
        '207':
          description: Multi-Status - Bulk delink processed with mixed results (some relations removed, some failed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResponse'
        '400':
          description: Bad Request - Various client errors
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/NotSupportedError'
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidRequestMethodError'
                - $ref: '#/components/schemas/AuthorizationFailedError'
                - $ref: '#/components/schemas/MandatoryNotFoundError'
                - $ref: '#/components/schemas/UnableToParseDataTypeError'
                - $ref: '#/components/schemas/RelationNotFoundBulkError'
                - $ref: '#/components/schemas/LimitExceededError'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidTokenError'
                - $ref: '#/components/schemas/OAuthScopeMismatchError'
        '403':
          description: Permission denied to delete related records
          content:
            application/json:
              schema:
                x-zs-$id: NoPermissionError
                $ref: '#/components/schemas/NoPermissionError'
        '404':
          description: Not Found - Parent record or related records do not exist
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RecordNotFoundError'
                - $ref: '#/components/schemas/InvalidUrlPatternError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                x-zs-$id: InternalError
                $ref: '#/components/schemas/InternalError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.DELETE
      tags:
      - Zoho CRM Related Records API
  /{parentRecordModule}/{parentRecord}/{relatedList}/{record}:
    get:
      summary: Get Specific Related Record
      description: Retrieves details of a specific record that is related to a parent record. Returns the record data along with pagination information if applicable.
      operationId: getRelatedRecord
      parameters:
      - $ref: '#/components/parameters/ParentRecordModule'
      - $ref: '#/components/parameters/ParentRecord'
      - $ref: '#/components/parameters/RelatedList'
      - $ref: '#/components/parameters/Record'
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          description: Successfully retrieved the specific related record
          content:
            application/json:
              schema:
                type: object
                description: Response containing a single related record with metadata
                additionalProperties: false
                required:
                - data
                properties:
                  data:
                    type: array
                    description: Array containing the single related record
                    maxItems: 1
                    items:
                      type: object
                      description: Related record object with requested fields
                      additionalProperties: true
                      properties:
                        id:
                          type: string
                          description: Unique identifier of the related record
                          pattern: ^[0-9]+$
                          maxLength: 20
                        Created_Time:
                          type: string
                          description: Timestamp when the record was created
                          format: date-time
                        Modified_Time:
                          type: string
                          description: Timestamp when the record was last modified
                          format: date-time
                        Moved_To__s:
                          type: string
                          description: Stage value to which the record was moved (stage history / picklist movement).
                          maxLength: 255
        '204':
          description: No related records found for the specified parent record
        '400':
          description: Bad Request - Various client errors
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/NotSupportedError'
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidRequestMethodError'
                - $ref: '#/components/schemas/AuthorizationFailedError'
                - $ref: '#/components/schemas/RequiredParamMissingError'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidTokenError'
                - $ref: '#/components/schemas/OAuthScopeMismatchError'
        '403':
          description: Permission denied to read related records
          content:
            application/json:
              schema:
                x-zs-$id: NoPermissionError
                $ref: '#/components/schemas/NoPermissionError'
        '404':
          description: Not Found - Record does not exist
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RecordNotFoundError'
                - $ref: '#/components/schemas/InvalidUrlPatternError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                x-zs-$id: InternalError
                $ref: '#/components/schemas/InternalError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.READ
      tags:
      - Zoho CRM Related Records API
    put:
      summary: Update Specific Related Record
      description: Updates a specific related record's properties.
      operationId: updateSpecificRelatedRecord
      parameters:
      - $ref: '#/components/parameters/ParentRecordModule'
      - $ref: '#/components/parameters/ParentRecord'
      - $ref: '#/components/parameters/RelatedList'
      - $ref: '#/components/parameters/Record'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request payload for updating a related record
              additionalProperties: false
              properties:
                data:
                  type: array
                  description: Array containing the record to update
                  minItems: 1
                  maxItems: 1
                  items:
                    type: object
                    description: Record update with ID and fields to modify
                    additionalProperties: true
                    required:
                    - id
                    properties:
                      id:
                        type: string
                        description: Unique identifier of the record to update
                        pattern: ^[0-9]+$
                        maxLength: 20
              required:
              - data
      responses:
        '200':
          description: Successfully updated the related record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResponse'
        '400':
          description: Bad Request - Various client errors
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/NotSupportedError'
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidRequestMethodError'
                - $ref: '#/components/schemas/AuthorizationFailedError'
                - $ref: '#/components/schemas/MandatoryNotFoundError'
                - $ref: '#/components/schemas/MandatoryNotFoundBulkError'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidTokenError'
                - $ref: '#/components/schemas/OAuthScopeMismatchError'
        '403':
          description: Permission denied to read related records
          content:
            application/json:
              schema:
                x-zs-$id: NoPermissionError
                $ref: '#/components/schemas/NoPermissionError'
        '404':
          description: Not Found - Record does not exist
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RecordNotFoundError'
                - $ref: '#/components/schemas/InvalidUrlPatternError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                x-zs-$id: InternalError
                $ref: '#/components/schemas/InternalError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.UPDATE
      tags:
      - Zoho CRM Related Records API
    delete:
      summary: Delink Specific Related Record
      description: Deletes the association between a parent record and a specific related record. This operation deletes only the relationship link, not the actual record itself.
      operationId: delinkSpecificRelatedRecord
      parameters:
      - $ref: '#/components/parameters/ParentRecordModule'
      - $ref: '#/components/parameters/ParentRecord'
      - $ref: '#/components/parameters/RelatedList'
      - $ref: '#/components/parameters/Record'
      responses:
        '200':
          description: Successfully delinked the related record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkOperationResponse'
        '400':
          description: Bad Request - Various client errors
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidModuleError'
                - $ref: '#/components/schemas/NotSupportedError'
                - $ref: '#/components/schemas/InvalidDataError'
                - $ref: '#/components/schemas/InvalidRequestMethodError'
                - $ref: '#/components/schemas/AuthorizationFailedError'
                - $ref: '#/components/schemas/MandatoryNotFoundError'
                - $ref: '#/components/schemas/UnableToParseDataTypeError'
        '401':
          description: Unauthorized - Invalid or missing authentication credentials
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InvalidTokenError'
                - $ref: '#/components/schemas/OAuthScopeMismatchError'
        '403':
          description: Permission denied to delete related records
          content:
            application/json:
              schema:
                x-zs-$id: NoPermissionError
                $ref: '#/components/schemas/NoPermissionError'
        '404':
          description: Not Found - Record does not exist or relationship not found
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/RecordNotFoundError'
                - $ref: '#/components/schemas/InvalidUrlPatternError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                x-zs-$id: InternalError
                $ref: '#/components/schemas/InternalError'
      security:
      - iam-oauth2-schema:
        - ZohoCRM.modules.DELETE
      tags:
      - Zoho CRM Related Records API
components:
  schemas:
    MandatoryNotFoundError:
      type: object
      description: Error response for missing required parameter.
      properties:
        code:
          type: string
          description: Error code.
          enum:
          - MANDATORY_NOT_FOUND
        message:
          type: string
          description: Error message.
          maxLength: 500
        status:
          type: string
          description: Status of the error.
          enum:
          - error
        details:
          type: object
          description: Additional error details.
          properties:
            param_name:
              type: string
              description: Name of the missing mandatory parameter (if applicable).
              maxLength: 100
            api_name:
              type: string
              description: API name of the missing mandatory field (if applicable).
              maxLength: 100
            json_path:
              type: string
              description: JSONPath to the missing field in request payload (if applicable).
              maxLength: 500
          additionalProperties: true
      required:
      - code
      - message
      - status
      additionalProperties: false
    MandatoryNotFoundBulkError:
      type: object
      description: Error response for mandatory field not found in bulk operations with data array wrapper.
      properties:
        data:
          type: array
          description: Array of error results
          minItems: 1
          maxItems: 100
          items:
            type: object
            description: Individual error result
            additionalProperties: false
            required:
            - code
            - status
            - message
            - details
            properties:
              code:
                type: string
                description: Error code.
                enum:
                - MANDATORY_NOT_FOUND
              details:
                type: object
                description: Error details with field information.
                additionalProperties: true
                properties:
                  api_name:
                    type: string
                    description: API name of the mandatory field that is missing
                    maxLength: 100
                  json_path:
                    type: string
                    description: JSONPath to the missing field in request payload
                    maxLength: 500
              message:
                type: string
                description: Error message.
                maxLength: 500
              status:
                type: string
                description: Status of the error.
                enum:
                - error
      required:
      - data
      additionalProperties: false
    InvalidUrlPatternError:
      type: object
      description: Error response when the request URL pattern is incorrect.
      properties:
        code:
          type: string
          description: Error code.
          enum:
          - INVALID_URL_PATTERN
        message:
          type: string
          description: Error message.
          maxLength: 500
        status:
          type: string
          description: Status of the error.
          enum:
          - error
        details:
          type: object
          description: Additional error details.
          additionalProperties: true
      required:
      - code
      - message
      - status
      additionalProperties: false
    InvalidModuleError:
      type: object
      description: Error response for invalid module name.
      properties:
        code:
          type: string
          description: Error code indicating the type of error.
          enum:
          - INVALID_MODULE
        message:
          type: string
          description: Detailed error message.
          maxLength: 500
        status:
          type: string
          description: Status of the error.
          enum:
          - error
        details:
          type: object
          description: Additional error details.
          properties:
            resource_path_index:
              type: integer
              format: int32
              description: Index of the path parameter that caused the error (0-based).
          additionalProperties: true
      required:
      - code
      - message
      - status
      additionalProperties: false
    AuthorizationFailedError:
      type: object
      description: Error response for insufficient privilege.
      properties:
        code:
          type: string
          description: Error code.
          enum:
          - AUTHORIZATION_FAILED
        message:
          type: string
          description: Error message.
          maxLength: 500
        status:
          type: string
          description: Status of the error.
          enum:
          - error
        details:
          type: object
          description: Additional error details.
          additionalProperties: true
      required:
      - code
      - message
      - status
      additionalProperties: false
    NotSupportedError:
      type: object
      description: Error response for modules not supported in the API.
      properties:
        code:
          type: string
          description: Error code indicating the type of error.
          enum:
          - NOT_SUPPORTED
        message:
          type: string
          description: Detailed error message.
          maxLength: 500
        status:
          type: string
          description: Status of the error.
          enum:
          - error
        details:
          type: object
          description: Additional error details.
          properties:
            resource_path_index:
              type: integer
              format: int32
              description: Index of the path parameter that caused the error (0-based).
          additionalProperties: true
      required:
      - code
      - message
      - status
      additionalProperties: false
    LimitExceededError:
      type: object
      description: Error response when the number of items exceeds the allowed limit.
      properties:
        code:
          type: string
          description: Error code.
          enum:
          - LIMIT_EXCEEDED
        message:
          type: string
          description: Error message.
          maxLength: 500
        status:
          type: string
          description: Status of the error.
          enum:
          - error
        details:
          type: object
          description: Additional error details including limit information.
          properties:
            limit:
              type: string
              description: Maximum allowed limit value
              maxLength: 10
            param_name:
              type: string
              description: Name of the parameter that exceeded the limit
              maxLength: 100
          additionalProperties: true
      required:
      - code
      - message
      - status
      additionalProperties: false
    RecordNotFoundError:
      type: object
      description: Error response for record not found.
      properties:
        code:
          type: string
          description: Error code.
          enum:
          - INVALID_DATA
        message:
          type: string
          description: Error message.
          maxLength: 500
        status:
          type: string
          description: Status of the error.
          enum:
          - error
        details:
          type: object
          description: Additional error details.
          additionalProperties: true
      required:
      - code
      - message
      - status
      additionalProperties: false
    RequiredParamMissingError:
      type: object
      description: Error response for missing required parameter.
      properties:
        code:
          type: string
          description: Error code.
          enum:
          - REQUIRED_PARAM_MISSING
        message:
          type: string
          description: Error message.
          maxLength: 500
        status:
          type: string
          description: Status of the error.
          enum:
          - error
        details:
          type: object
          description: Additional error details.
          properti

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