Zoho CRM Related Records API

{
  "openapi": "3.1.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"
        }
      }
    }
  ],
  "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"
            ]
          }
        ]
      },
      "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"
            ]
          }
        ]
      },
      "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"
            ]
          }
        ]
      }
    },
    "/{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"
            ]
          }
        ]
      },
      "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"
            ]
          }
        ]
      },
      "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": "#/componen

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