Zoho CRM Fields API

{
  "openapi": "3.1.0",
  "info": {
    "title": "Fields API",
    "description": "To get the field metadata for the specified module including standard module, custom module, subform module, and linking module in you Zoho CRM account. The fields displayed are from all layouts for the module. The response does not contain layout-specific fields like mandatory fields or picklist values.",
    "version": "8"
  },
  "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": {
    "/settings/fields": {
      "get": {
        "summary": "Get Fields",
        "description": "Retrieve all fields metadata for modules. Examples and schemas derived from provided sample and schema files.",
        "operationId": "getFields",
        "parameters": [
          {
            "$ref": "#/components/parameters/Module",
            "description": "Module name passed as parameter is case insensitive. For example, the module name 'Leads'."
          },
          {
            "$ref": "#/components/parameters/Includes",
            "description": "It specifies whether to include the allowed_permissions JSON object in the response"
          },
          {
            "$ref": "#/components/parameters/Type",
            "description": "The type of fields to be retrieved. Example: 'used', 'unused', etc."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with fields metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Response object containing an array of fields.",
                  "properties": {
                    "fields": {
                      "type": "array",
                      "description": "An array of field metadata objects.",
                      "items": {
                        "$ref": "#/components/schemas/FieldSchema"
                      },
                      "maxItems": 100
                    }
                  },
                  "required": [
                    "fields"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "204": {
            "description": "No Content. The request was successful and no response body is returned."
          },
          "400": {
            "description": "Bad Request — When Invalid Module Name is Given error will be thrown ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvalidModuleName"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.fields.READ"
            ]
          }
        ]
      },
      "post": {
        "summary": "Create Fields",
        "description": "To create custom fields in a module in your Zoho CRM account.",
        "operationId": "postFields",
        "parameters": [
          {
            "$ref": "#/components/parameters/Module",
            "description": "Module name passed as parameter is case insensitive. For example, the module name 'Leads'."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FieldRequestBodySchema"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Fields created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateFieldsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request — List of Bad Request that can occure while creating the field",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "type": "object",
                      "description": "Response object containing an array of errors.",
                      "properties": {
                        "fields": {
                          "type": "array",
                          "description": "An array of field metadata objects.",
                          "items": {
                            "$ref": "#/components/schemas/ErrorResponse"
                          },
                          "maxItems": 5
                        }
                      },
                      "required": [
                        "fields"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.fields.CREATE"
            ]
          }
        ]
      },
      "patch": {
        "summary": "Update Fields",
        "description": "To update custom fields in your Zoho CRM account.",
        "operationId": "patchFields",
        "parameters": [
          {
            "$ref": "#/components/parameters/Module",
            "description": "Module name passed as parameter is case insensitive. For example, the module name 'Leads'."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FieldUpdateRequestBodySchema"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fields updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateFieldsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request — Possible Errors that can occure while updating fields",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "type": "object",
                      "description": "Response object containing an array of errors.",
                      "properties": {
                        "fields": {
                          "type": "array",
                          "description": "An array of field metadata objects.",
                          "items": {
                            "$ref": "#/components/schemas/ErrorResponse"
                          },
                          "maxItems": 5
                        }
                      },
                      "required": [
                        "fields"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.fields.UPDATE"
            ]
          }
        ]
      }
    },
    "/settings/fields/{fieldId}": {
      "get": {
        "summary": "Get Field by ID",
        "description": "Retrieve metadata of a specific custom field in a module using the field ID.",
        "operationId": "getFieldsWithID",
        "parameters": [
          {
            "$ref": "#/components/parameters/Module",
            "description": "Module name passed as parameter is case insensitive. For example, the module name 'Leads'."
          },
          {
            "name": "fieldId",
            "in": "path",
            "description": "Unique ID of the custom field to be retrieved",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Id"
            }
          },
          {
            "$ref": "#/components/parameters/Includes",
            "description": "It specifies whether to include the allowed_permissions JSON object in the response"
          },
          {
            "$ref": "#/components/parameters/Type",
            "description": "The type of fields to be retrieved. Example: 'used', 'unused', etc."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with fields metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Response object containing an array of fields.",
                  "properties": {
                    "fields": {
                      "type": "array",
                      "description": "An array of field metadata objects.",
                      "items": {
                        "$ref": "#/components/schemas/FieldSchema"
                      },
                      "maxItems": 1
                    }
                  },
                  "required": [
                    "fields"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Bad Request — canonical error shapes for invalid id, already scheduled, conversion in progress, association limits, or system-defined restrictions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequest"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        },
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.fields.READ"
            ]
          }
        ]
      },
      "patch": {
        "summary": "Update Field by ID",
        "description": "Update a Custom Field with related to specific module of Zoho CRM Account",
        "operationId": "putFieldsWithId",
        "parameters": [
          {
            "$ref": "#/components/parameters/Module",
            "description": "Module name passed as parameter is case insensitive. For example, the module name 'Leads'."
          },
          {
            "name": "fieldId",
            "in": "path",
            "description": "ID of the custom field to delete",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Id"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FieldUpdateRequestBodySchema"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Field updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Response object containing an array of fields.",
                  "properties": {
                    "fields": {
                      "type": "array",
                      "description": "An array of field metadata objects.",
                      "items": {
                        "$ref": "#/components/schemas/FieldCreationResult"
                      },
                      "maxItems": 1
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Bad Request — canonical error shapes for invalid id, already scheduled, conversion in progress, association limits, or system-defined restrictions.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ErrorResponse"
                    },
                    {
                      "type": "object",
                      "description": "Response object containing an array of errors.",
                      "properties": {
                        "fields": {
                          "type": "array",
                          "description": "An array of field metadata objects.",
                          "items": {
                            "$ref": "#/components/schemas/ErrorResponse"
                          },
                          "maxItems": 100
                        }
                      },
                      "required": [
                        "fields"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.fields.UPDATE"
            ]
          }
        ]
      },
      "delete": {
        "summary": "Delete Custom Field",
        "description": "Delete a custom field from a module. Field must not be used in workflows, approvals, scoring rules, or other configurations. Only one field can be deleted per request.",
        "operationId": "deleteCustomField",
        "parameters": [
          {
            "name": "fieldId",
            "in": "path",
            "description": "ID of the custom field to delete",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Id"
            }
          },
          {
            "$ref": "#/components/parameters/Module",
            "description": "Module name passed as parameter is case insensitive. For example, the module name 'Leads'."
          }
        ],
        "responses": {
          "200": {
            "description": "Field deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Response object containing an array of fields.",
                  "properties": {
                    "fields": {
                      "type": "array",
                      "description": "An array of field metadata objects.",
                      "items": {
                        "$ref": "#/components/schemas/FieldCreationResult"
                      },
                      "maxItems": 1
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid field ID, field in use, or missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication failure or insufficient scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found - Invalid URL or field not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "iam-oauth2-schema": [
              "ZohoCRM.settings.fields.DELETE"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "iam-oauth2-schema": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://accounts.zoho.com/oauth/v2/auth",
            "tokenUrl": "https://accounts.zoho.com/oauth/v2/token",
            "refreshUrl": "https://accounts.zoho.com/oauth/v2/token",
            "scopes": {
              "ZohoCRM.settings.fields.READ": "Allows read access to fields in Zoho CRM settings",
              "ZohoCRM.settings.fields.CREATE": "Allows  To create a Custom Field ",
              "ZohoCRM.settings.fields.UPDATE": "Allows  To Update a Custom Field ",
              "ZohoCRM.settings.fields.DELETE": "Allows  To Delete a Custom Field ",
              "ZohoCRM.settings.fields.ALL": "Allows all access to fields in Zoho CRM settings",
              "ZohoCRM.settings.all": "Allows all access to Zoho CRM settings"
            }
          }
        }
      }
    },
    "parameters": {
      "Module": {
        "description": "The API name of the module to which the field belongs.",
        "name": "module",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "maxLength": 30,
          "description": "The API name of the module to which the field belongs."
        }
      },
      "Includes": {
        "description": "To include additional information about the field's permissions to update.",
        "name": "include",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "description": "To include additional information about the field's permissions to update.",
          "maxLength": 50,
          "enum": [
            "allowed_permissions_to_update",
            "skip_field_permissionz"
          ]
        }
      },
      "Type": {
        "description": "The usage type of the field.",
        "name": "type",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 10,
          "enum": [
            "all",
            "unused",
            "used"
          ]
        }
      }
    },
    "schemas": {
      "InternalServerError": {
        "type": "object",
        "description": "Internal server error response object containing code, message, details, and status.",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code indicating the type of error.",
            "maxLength": 50
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message.",
            "maxLength": 255
          },
          "details": {
            "type": "object",
            "description": "Additional details about the error.",
            "additionalProperties": true
          },
          "status": {
            "type": "string",
            "maxLength": 50,
            "description": "Status of the error response.",
            "enum": [
              "error"
            ]
          }
        },
        "required": [
          "code",
          "message",
          "details",
          "status"
        ],
        "additionalProperties": false
      },
      "InvalidModuleName": {
        "type": "object",
        "description": "When Invalid Module Name is passed this error will be thrown",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "maxLength": 50,
            "description": "Error code.",
            "pattern": "^[A-Z_]+$"
          },
          "details": {
            "type": "object",
            "description": "Additional error details.",
            "additionalProperties": true
          },
          "message": {
            "type": "string",
            "description": " error message.",
            "maxLength": 255
          },
          "status": {
            "type": "string",
            "maxLength": 50,
            "description": "Status of the error."
          }
        },
        "required": [
          "code",
          "details",
          "message",
          "status"
        ]
      },
      "BadRequest": {
        "type": "object",
        "description": "Standard error response object.",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "maxLength": 50,
            "description": "Error code.",
            "pattern": "^[A-Z_]+$"
          },
          "details": {
            "type": "object",
            "description": "Additional error details.",
            "additionalProperties": true
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message.",
            "maxLength": 255
          },
          "status": {
            "type": "string",
            "maxLength": 50,
            "description": "Status of the error.",
            "pattern": "^error$"
          }
        },
        "required": [
          "code",
          "details",
          "message",
          "status"
        ]
      },
      "ApiName": {
        "type": "string",
        "description": "API name of the resource. It will start with alphabets and can contain alphanumeric characters and underscores.",
        "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
        "maxLength": 50
      },
      "Id": {
        "type": "string",
        "description": "Id of the resource.",
        "format": "int64"
      },
      "ModuleName": {
        "type": "string",
        "description": "Name of the module",
        "maxLength": 100
      },
      "TypeNull": {
        "type": "null",
        "description": "Null if no information is available."
      },
      "FieldSchema": {
        "type": "object",
        "description": "Schema representing a field in the module.",
        "properties": {
          "associated_module": {
            "oneOf": [
              {
                "type": "object",
                "description": "Gives detail related to the associated module LIKE subform",
                "properties": {
                  "module": {
                    "$ref": "#/components/schemas/ModuleName"
                  },
                  "id": {
                    "$ref": "#/components/schemas/Id"
                  }
                },
                "required": [
                  "module",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "$ref": "#/components/schemas/TypeNull"
              }
            ]
          },
          "webhook": {
            "type": "boolean",
            "description": "Wether webhook is enabled for the field"
          },
          "operation_type": {
            "type": "object",
            "additionalProperties": false,
            "description": "Operation types allowed for the field",
            "properties": {
              "web_update": {
                "type": "boolean",
                "description": "Wether any operation is allowed through web update"
              },
              "api_create": {
                "type": "boolean",
                "description": "Wether any operation is allowed through API create"
              },
              "web_create": {
                "type": "boolean",
                "description": "Wether any operation is allowed through web create"
              },
              "api_update": {
                "type": "boolean",
                "description": "Wether any operation is allowed through API update"
              }
            },
            "required": [
              "web_update",
              "api_create",
              "web_create",
              "api_update"
            ]
          },
          "colour_code_enabled_by_system": {
            "type": "boolean",
            "description": "Wether any colour code is enabled by system"
          },
          "field_label": {
            "type": "string",
            "description": "Plural label of the module.",
            "maxLength": 50
          },
          "tooltip": {
            "oneOf": [
              {
                "type": "object",
                "description": "if tool tip is enabled then it will return the information",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "it gives the name of the tool tip",
                    "maxLength": 25
                  },
                  "value": {
                    "type": "string",
                    "description": "Text for the tool tip",
                    "maxLength": 255
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "additionalProperties": false
              },
              {
                "$ref": "#/components/schemas/TypeNull"
              }
            ]
          },
          "display_format_properties": {
            "oneOf": [
              {
                "type": "object",
                "description": "if display format properties is available then it will return the information",
                "properties": {
                  "split": {
                    "type": "number",
                    "description": "for phone it will return the split value",
                    "format": "int32"
                  },
                  "radio_display_type": {
                    "type": "string",
                    "description": "for radiobutton it will return the display type",
                    "maxLength": 25
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              {
                "$ref": "#/components/schemas/TypeNull"
              }
            ]
          },
          "type": {
            "type": "string",
            "description": "Type of the field used or unused.",
            "maxLength": 25
          },
          "field_read_only": {
            "type": "boolean",
            "description": "Wether field is read only"
          },
          "customizable_properties": {
            "oneOf": [
              {
                "type": "array",
                "description": "Customizable properties of the field",
                "items": {
                  "type": "string",
                  "description": "A customizable property of the field",
                  "maxLength": 50
                },
                "maxItems": 100
              },
              {
                "$ref": "#/components/schemas/TypeNull"
              }
            ]
          },
          "display_label": {
            "type": "string",
            "description": "Display label of the field.",
            "maxLength": 50
          },
          "read_only": {
            "type": "boolean",
            "description": "Wether field is read only"
          },
          "association_details": {
            "oneOf": [
              {
                "type": "object",
                "description": "if association details is available then it will return the information",
                "properties": {
                  "related_field": {
                    "type": "object",
                    "description": "Details of the related field",
                    "properties": {
                      "api_name": {
                        "$ref": "#/components/schemas/ApiName"
                      },
                      "id": {
                        "$ref": "#/components/schemas/Id"
                      }
                    },
                    "required": [
                      "api_name",
                      "id"
                    ],
                    "additionalProperties": false
                  },
                  "lookup_field": {
                    "type": "object",
                    "description": "Details of the lookup field",
                    "properties": {
                      "api_name": {
                        "$ref": "#/components/schemas/ApiName"
                      },
                      "id": {
                        "$ref": "#/components/schemas/Id"
                      }
                    },
                    "required": [
                      "api_name",
                      "id"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "related_field",
                  "lookup_field"
                ],
                "additionalProperties": false
              },
              {
                "$ref": "#/components/schemas/TypeNull"
              }
            ]
          },
          "businesscard_supported": {
            "type": "boolean",
            "description": "Wether business card is supported for the field"
          },
          "multi_module_lookup": {
            "oneOf": [
              {
                "type": "object",
                "description": "if multi module lookup is available then it will return the information",
                "properties": {
                  "display_label": {
                    "type": "string",
                    "description": "Display label of the multi module lookup",
                    "maxLength": 50
                  },
                  "api_name": {
                    "$ref": "#/components/schemas/ApiName"
                  },
                  "modules": {
                    "type": "array",
                    "description": "List of modules associated with the multi module lookup",
                    "items": {
                      "type": "object",
                      "description": "Details of the module",
                      "properties": {
                        "api_name": {
                          "$ref": "#/components/schemas/ApiName"
                        },
                        "module_name": {
                          "type": "string",
                          "description": "Name of the module",
                          "maxLength": 50
                        },
                        "id": {
                          "$ref": "#/components/schemas/Id"
                        }
                      },
                      "required": [
                        "api_name",
                        "module_name",


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