The Zoho CRM Records API allows you to perform CRUD (Create, Read, Update, Delete) operations on records across all modules in your CRM. Use this API to retrieve, create, update, delete, upsert, and clone records.
{
"openapi": "3.1.0",
"info": {
"title": "Records",
"description": "The Zoho CRM Records API allows you to perform CRUD (Create, Read, Update, Delete) operations on records across all modules in your CRM. Use this API to retrieve, create, update, delete, upsert, and clone records.",
"version": "8.0"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"enum": [
"com",
"eu",
"in",
"cn",
"au"
],
"default": "com",
"description": "API Server URL TLD"
},
"version": {
"default": "v8",
"description": "API Version"
}
}
}
],
"paths": {
"/{module}": {
"get": {
"operationId": "getRecords",
"description": "To get the list of available records from a module",
"summary": "Get Records for a specific module",
"parameters": [
{
"$ref": "#/components/parameters/Module"
},
{
"$ref": "#/components/parameters/Fields"
},
{
"$ref": "#/components/parameters/TerritoryId"
},
{
"$ref": "#/components/parameters/Ids"
},
{
"$ref": "#/components/parameters/Cvid"
},
{
"$ref": "#/components/parameters/PerPage"
},
{
"$ref": "#/components/parameters/Page"
},
{
"$ref": "#/components/parameters/PageToken"
},
{
"$ref": "#/components/parameters/SortOrder"
},
{
"$ref": "#/components/parameters/SortBy"
},
{
"$ref": "#/components/parameters/Converted"
},
{
"$ref": "#/components/parameters/IncludeChild"
}
],
"responses": {
"200": {
"description": "Successful response containing the list of records for the specified module",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordGETSucessResponse"
}
}
}
},
"204": {
"description": "No Content - The request was successful, but no records found."
},
"400": {
"description": "Bad Request - The request could not be processed due to invalid input, missing mandatory parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordGETErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden - User lacks permission to access the requested module, Records or This API is supported only for admin users.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordPermissionResponse"
}
}
}
},
"404": {
"description": "Not Found - The requested URL pattern is invalid or the specified resource does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordInvalidURLResponse"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordInternalErrorResponse"
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Leads.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Contacts.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Accounts.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Deals.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Tasks.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Events.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Calls.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Products.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Vendors.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Campaigns.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Cases.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Solutions.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Quotes.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Invoices.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Forecasts.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Activities.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Notes.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Attachments.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.custom.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.READ"
]
}
]
},
"post": {
"operationId": "createRecords",
"summary": "Create a Record in a specific module",
"description": "Create a Record in a specific module",
"parameters": [
{
"$ref": "#/components/parameters/Module"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"description": "The request body for Records Post",
"$ref": "#/components/schemas/RecordsInputSchema"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Record is created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordSuccessResponse"
}
}
}
},
"400": {
"description": "Bad Request - The request could not be processed due to invalid input, missing mandatory parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordsErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized - Authentication failed or insufficient OAuth scope permissions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordUnathorizedResponse"
}
}
}
},
"403": {
"description": "Forbidden - User lacks permission add records to the requested module, Records or This API is supported only for admin users.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordPermissionResponse"
}
}
}
},
"404": {
"description": "Not Found - The requested URL pattern is invalid or the specified resource does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordInvalidURLResponse"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordInternalErrorResponse"
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Leads.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Contacts.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Accounts.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Deals.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Tasks.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Events.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Calls.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Products.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Vendors.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Campaigns.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Cases.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Solutions.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Quotes.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Invoices.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Forecasts.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Activities.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Notes.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Attachments.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.custom.CREATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.CREATE"
]
}
]
},
"put": {
"operationId": "updateRecords",
"description": "To update existing entities or records in a specified module.",
"summary": "To update existing entities or records in a specified module",
"parameters": [
{
"$ref": "#/components/parameters/Module"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"description": "Request body containing the updated resource data to modify the existing record.",
"$ref": "#/components/schemas/RecordsInputSchema"
}
}
}
},
"responses": {
"200": {
"description": "Success Response containing the record id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordSuccessResponse"
}
}
}
},
"400": {
"description": "Failure in Record Update",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordsErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized - Authentication failed or insufficient OAuth scope permissions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordUnathorizedResponse"
}
}
}
},
"403": {
"description": "Forbidden - User lacks permission update records in the requested module, Records or This API is supported only for admin users.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordPermissionResponse"
}
}
}
},
"404": {
"description": "Not Found - The requested URL pattern is invalid or the specified resource does not exist.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordInvalidURLResponse"
}
}
}
},
"412": {
"description": "The record was modified after the time specified.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Root response object returned when a record update fails due to concurrent modification.",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"description": "List of error objects describing why the request failed.",
"maxItems": 1,
"items": {
"type": "object",
"description": "Error object representing a single record modification conflict.",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code indicating the type of failure.",
"enum": [
"ALREADY_MODIFIED"
]
},
"message": {
"type": "string",
"description": "Human-readable explanation of the error.",
"maxLength": 1024
},
"status": {
"type": "string",
"description": "Overall execution status of the request.",
"enum": [
"error"
]
},
"details": {
"type": "object",
"description": "Additional metadata describing the record state at the time of conflict.",
"additionalProperties": true,
"properties": {
"Modified_Time": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the record was last modified."
},
"Created_Time": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the record was originally created."
},
"id": {
"type": "string",
"description": "Unique identifier of the record that caused the conflict.",
"format": "int64"
},
"Modified_By": {
"type": "object",
"additionalProperties": false,
"description": "User who last modified the record.",
"properties": {
"name": {
"type": "string",
"description": "Display name of the modifying user.",
"maxLength": 255
},
"id": {
"type": "string",
"description": "Unique identifier of the modifying user.",
"format": "int64"
}
},
"required": [
"name",
"id"
]
},
"Created_By": {
"type": "object",
"additionalProperties": false,
"description": "User who originally created the record.",
"properties": {
"name": {
"type": "string",
"description": "Display name of the creating user.",
"maxLength": 255
},
"id": {
"type": "string",
"description": "Unique identifier of the creating user.",
"format": "int64"
}
},
"required": [
"name",
"id"
]
}
}
}
},
"required": [
"code",
"message",
"status"
]
}
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecordInternalErrorResponse"
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Leads.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Contacts.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Accounts.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Deals.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Tasks.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Events.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Calls.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Products.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Vendors.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Campaigns.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Cases.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Solutions.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Quotes.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Invoices.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Forecasts.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Activities.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Notes.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.Attachments.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.custom.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.modules.UPDATE"
]
}
]
},
"delete": {
"operationId": "deleteRecords",
"summary": "Delete multiple records from a module",
"description": "Permanently deletes one or more records from the specified module using comma-separated record IDs. Returns per-item results for bulk operations.",
"parameters": [
{
"$ref": "#/components/parameters/Module"
},
{
"$ref": "#/components/parameters/Ids"
}
],
"responses": {
"200": {
"description": "Successful deletion. Returns a success status for each deleted record.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response schema returned when one or more records are successfully deleted.",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"description": "List of successfully deleted records with individual success details.",
"maxItems": 100,
"items": {
"type": "object",
"description": "Success object representing a single deleted record.",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Machine-readable code indicating successful deletion.",
"enum": [
"SUCCESS"
]
},
"details": {
"type": "object",
"description": "Additional metadata related to the deleted record.",
"additionalProperties": true,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the record that was deleted.",
"format": "int64"
}
},
"required": [
"id"
]
},
"message": {
"type": "string",
"description": "Human-readable confirmation message for the deletion.",
"enum": [
"record deleted"
]
},
"status": {
"type": "string",
"description": "Overall execution status of the delete operation for the record.",
"enum": [
"success"
]
}
},
"required": [
"code",
"details",
"message",
"status"
]
}
}
},
"required": [
"data"
]
}
}
}
},
"207": {
"description": "Multi-status response indicating that some records were deleted successfully while others failed.",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response returned when a bulk delete operation results in mixed success and failure outcomes.",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"description": "List of per-record results indicating whether each record deletion succeeded or failed.",
"maxItems": 100,
"items": {
"oneOf": [
{
"type": "object",
"description": "Represents a successfully deleted record.",
"additionalProperties": false,
"properties": {
"status": {
"type": "string",
"description": "Indicates that the delete operation for the record was successful.",
"enum": [
"success"
]
},
"code": {
"type": "string",
"description": "Success code returned for a deleted record.",
"enum": [
"SUCCESS"
]
},
"message": {
"type": "string",
"description": "Message confirming successful deletion of the record.",
"maxLength": 1024
},
"details": {
"type": "object",
"description": "Additional information about the deleted record.",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the deleted record.",
"format": "int64"
}
}
}
},
"required": [
"status",
"code",
"message",
"details"
]
},
{
"type": "object",
"additionalProperties": false,
"description": "Represents a record deletion failure.",
"properties": {
"status": {
"type": "string",
"description": "Indicates that the delete operation for the record failed.",
"enum": [
"error"
]
},
"code": {
"type": "string",
"description": "Error code describing why the record could not be deleted.",
"enum": [
"INVALID_DATA",
"REQUIRED_PARAM_MISSING"
]
},
"message": {
"type": "string",
"description": "Message explaining the reason for the deletion failure.",
"maxLength": 1024
},
"details": {
"type": "object",
"description": "Additional context about the deletion error.",
"additionalProperties": true,
"properties": {
"api_name": {
"type": "string",
"description": "API name associated with the error.",
"maxLength": 255
},
"id": {
"type": "string",
"format": "int64",
"description": "Identifier of the record that failed to delete."
},
"param": {
"type": "string",
"maxLength": 1024,
"description": "Request parameter that caused the error."
},
"param_name": {
"type": "string",
"maxLength": 255,
"description": "Name of the invalid or missing parameter."
}
}
}
},
"required": [
"status",
"code",
"message",
"details"
]
}
]
}
}
}
}
}
}
},
"400": {
"description": "Bad request due to invalid module, missing parameters, or invalid record IDs.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Response schema returned when one or more records fail to delete due to invalid data in a bulk delete operation.",
"properties": {
"data": {
"type": "array",
"description": "List of error objects for each record that failed to delete.",
# --- truncated at 32 KB (146 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-record-openapi.json