Zoho CRM Zoho CRM Related Records API

openapi: 3.2.0
info:
  title: Zoho CRM Related Records API
  description: RESTful API for managing relationships between CRM records across different modules. Provides comprehensive operations for retrieving, updating, and delinking related records with support for bulk operations, field filtering, and pagination. Supports all standard CRM modules including Contacts, Leads, Deals, Accounts, Products, and custom modules.
  version: '8'
servers:
- url: https://zohoapis.{dc}/crm/{version}
  description: API Server URL
  variables:
    dc:
      description: API Server URL TLD
      default: com
      enum:
      - com
      - eu
      - in
      - cn
      - au
    version:
      description: API version
      default: v8
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:
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: Page number for pagination (starting from 1)
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 10000
        default: 1
    ParentRecord:
      name: parentRecord
      in: path
      required: true
      description: The unique identifier of the parent record. Must be a valid numeric record ID.
      schema:
        type: string
        pattern: ^[0-9]+$
        maxLength: 20
    Record:
      name: record
      in: path
      required: true
      description: The unique identifier of the specific related record. Must be a valid numeric record ID.
      schema:
        type: string
        pattern: ^[0-9]+$
        maxLength: 20
    IfModifiedSince:
      name: If-Modified-Since
      in: header
      required: false
      description: Only return records modified after this timestamp (RFC 2822 format)
      schema:
        type: string
        format: date-time
    ParentRecordModule:
      name: parentRecordModule
      in: path
      required: true
      description: The module name of the parent record (e.g., Contacts, Leads, Deals, Accounts, Services__s, Price_Books)
      schema:
        type: string
        pattern: ^[A-Za-z_][A-Za-z0-9_]*$
        maxLength: 100
    SortBy:
      name: sort_by
      in: query
      required: false
      description: 'Field to sort records by. Allowed: id, Created_Time, Modified_Time.'
      schema:
        type: string
        enum:
        - id
        - Created_Time
        - Modified_Time
        default: id
    Converted:
      name: converted
      in: query
      required: false
      description: Filter for converted records.
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
        - both
        default: 'false'
    IdsOptional:
      name: ids
      in: query
      required: false
      description: Comma-separated list of record IDs to retrieve.
      schema:
        type: string
        pattern: ^[0-9]+(,[0-9]+)*$
        maxLength: 2000
    SortOrder:
      name: sort_order
      in: query
      required: false
      description: Sort order for records.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
    Fields:
      name: fields
      in: query
      required: true
      description: Comma-separated list of field names to include in the response. Field names must follow API naming conventions.
      schema:
        type: string
        pattern: ^[A-Za-z_][A-Za-z0-9_]*(,[A-Za-z_][A-Za-z0-9_]*)*$
        maxLength: 1000
    PageToken:
      name: page_token
      in: query
      required: false
      description: Token for fetching the next set of records after 2000. Use the value from 'next_page_token' in the previous response.
      schema:
        type: string
        maxLength: 500
    Ids:
      name: ids
      in: query
      required: true
      description: Comma-separated list of record IDs to delink from the parent record. Each ID must be numeric.
      schema:
        type: string
        pattern: ^[0-9]+(,[0-9]+)*$
        maxLength: 2000
    PerPage:
      name: perPage
      in: query
      required: false
      description: Number of records to return per page
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 200
        default: 200
    RelatedList:
      name: relatedList
      in: path
      required: true
      description: The name of the related list (module) containing the records to retrieve or modify
      schema:
        type: string
        pattern: ^[A-Za-z_][A-Za-z0-9_]*$
        maxLength: 100
  schemas:
    NoPermissionError:
      type: object
      description: Error response for permission denied.
      properties:
        code:
          type: string
          description: Error code.
          enum:
          - NO_PERMISSION
        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:
            permissions:
              type: array
              description: Missing/required permissions for the requested operation
              maxItems: 100
              items:
                type: string
                description: Permission identifier string.
                maxLength: 200
          additionalProperties: true
      required:
      - code
      - message
      - status
      additionalProperties: false
    BulkOperationResponse:
      type: object
      description: Response structure for bulk operations (update, delete)
      additionalProperties: false
      required:
      - data
      properties:
        data:
          type: array
          description: Array of operation results per record
          maxItems: 100
          items:
            type: object
            description: Individual operation result
            additionalProperties: false
            required:
            - code
            - status
            properties:
              code:
                type: string
                description: Result code for the operation
                enum:
                - SUCCESS
                - INVALID_DATA
                - DUPLICATE_DATA
                - MANDATORY_NOT_FOUND
              details:
                type: object
                description: Operation details including affected record ID
                additionalProperties: true
                properties:
                  id:
                    type: string
                    description: ID of the affected record
                    pattern: ^[0-9]+$
                    maxLength: 20
                  api_name:
                    type: string
                    description: API name of the field that caused the error (if applicable).
                    maxLength: 100
                  json_path:
                    type: string
                    description: JSONPath to the field in request payload (if applicable).
                    maxLength: 500
                  param_name:
                    type: string
                    description: Parameter name that caused the error (if applicable).
                    maxLength: 100
              message:
                type: string
                description: Human-readable result message
                maxLength: 500
              status:
                type: string
                description: Operation status
                enum:
                - success
                - error
    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:
             

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