Create Custom Fields

Purpose

To create custom fields in a module in your Zoho CRM account.

Endpoints

POST /settings/fields?module={module_API_name}

Request Details

Request URL

{api-domain}/crm/{version}/settings/fields

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.fields.CREATE (or)
ZohoCRM.settings.fields.ALL (or)
ZohoCRM.settings.ALL

Parameters

modulestring, mandatory
Specify the module in which you want to create custom fields. Use the GET - Modules API to retrieve modules API names and IDs.
Supported modules: Leads, Contacts, Accounts, Campaigns, Cases, Invoices, Deals, Price Books, Products, Purchase Orders, Quotes, Sales Orders, Solutions, Vendors, Calls, Tasks, Events, Users, DealHistory, QuotedItems, OrderedItems, PurchaseItems, InvoicedItems, Visits, Services, Appointments, and Custom.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/fields?module=Leads"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"
-X POST

Input JSON

field_labelstring, mandatory
It represents the unique display label of the field.
data_typestring, mandatory
It represents the data type of the field. See Field Types: Data Types and Length Limits for more information on the available data types.
lengthinteger, optional
It represents the maximum number of characters allowed for a field. Certain fields have specific character limits. See Field Types: Data Types and Length Limits for more information.
tooltipJSON object, optional
Represents the tooltip content for the field.
Possible names:
static_text : Specifies that the field should have a static text tootltip. The tooltip content will be displayed in the field when the user clicks on the field box.
info_icon : Specifies that the field should have aninfo icontooltip. Clicking on the "info icon" will display the tooltip contents.
Note that it is mandatory to specify both the name and value when you specify tootltip key.
profilesJSON array, optional
Each object in the array represents the name and ID of the profile that has access to the field. By default, all organization users will have access to the field. Possible permission types: read_write, read_only, and hidden.
- read_write: The user has read and write permissions for the field.
- read_only: The user has only read permission for the field.
- hidden: The field is not visible to the user.
Note that it is mandatory to specify a permission type to the profiles in order to access the field.
filterableBoolean, optional
Represents whether the created field is supported in filters or not. By default, its value is true. The filterable key is supported for all data types except imageupload, fileupload, textarea, and formula when its return_type is text.
uniqueJSON object, optional
It specifies whether to mark the field as a unique field or not. The accepted value for case_sensitive is false.
hipaa_compliance_enabledBoolean, optional
This key helps you decide how you want to manage and process health related data of your customers to comply with HIPAA. To use this key, please enable it through the UI. For that, Go to Setup > Security Control > Compliance Setting > HIPAA Compliance.
Note: The hipaa_compliance_enabled key supports all field data types.
privateJSON object, optional
This key decide how you want to handle, manage, and process personal data of your customers to comply with GDPR for your organization. To use this key, please enable it through the UI. For that, Go to Setup > Security Control > Compliance Setting > GDPR Compliance.
Note: The private key supports all field data types.
Possible values for the type : Low and High.
cryptJSON object, optional
Represents whether to store the field's value in encrypted form or not.
The possible values are:
decryption - The field's value will not be stored in encrypted form. The default value is decryption.
encryption - The field's value will be stored in encrypted form. This is supported for the following data types : text, textarea, email, phone, date, datetime, integer, currency, bigint, double, and website.

Field Types: Data Types and Length Limits

The table below presents a list of field types, their corresponding data types, and the associated length limits:

Field Type	Field Data Type (Example: "data_type": "text")	Number of characters allowed for a field ( Example: "length": 150)
Text	text	1 to 255
Text Area	textarea	2000 or 32000 or 50000
Email	email	1 to 100
Phone	phone	1 to 30
Integer	integer	1 to 9
Auto Number	autonumber	1 to 255
Currency	currency	1 to 16
Percent	percent	1 to 5
BigInt	bigint	1 to 18
Double	double	1 to 18
Website	website	1 to 450
File Upload	fileupload	1 or 5
Image Upload	imageupload	1 to 10

Note

The same sample input format is applicable to the data types email and phone, supporting both the static_text and info_icon values for the tooltip key.
The fields will be created in your standard layout.
A maximum of five fields can be created in a single API call.
The filterable key is supported for all data types except imageupload, fileupload, textarea, and formula when its return_type is text.
The data types email and textarea do not support external fields.
In the tooltip key, the static_text value is limited to 35 characters, and the info_icon value is limited to 255 characters.
You can create a maximum of two unique fields per module in all the editions.
You can create a maximum of one Auto-Number field in a module.
The hipaa_compliance_enabled and private keys support all field data types.
The maximum number of custom fields possible varies depending on the CRM edition.
- Standard - Maximum of 10 fields per module.
- Professional - Maximum of 155 fields per module.
- Enterprise - Maximum of 300 fields per module.
- Ultimate - Maximum of 500 fields per module.

Please refer to feature-wise comparison of Zoho CRM Editions to know more about the custom fields limits based on different editions.

Sample Input : Field Type - Text

Copied{
    "fields": [
        {
            "field_label": "Your Name",
            "data_type": "text",  // Specify the data type as text*
            "length": 150,
            "filterable": true,
            "tooltip": {
                "name": "static_text",
                "value": "Enter your name"
            },
            "profiles": [
                {
                    "id": "2423488000000015972",
                    "permission_type": "read_write"
                },
                {
                    "id": "2423488000000015975",
                    "permission_type": "read_only"
                }
            ],
             "external": {
                "type": "user",
                "show": false
            },
              "crypt": {
                "mode": "decryption"
            }
        }
    ]
}

Sample Response

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "111112000000067259"
            },
            "message": "field created",
            "status": "success"
        }
    ]
}

Sample successful response for a single field creation.

Input JSON

"Text Area" ("data_type": "textarea")

textareaJSON object, mandatory
It is a multi-line text area field that allows you to add additional information to the record. The following represents the possible values of "type" key, along with its allowed characters.
- small - It is a text area type that allows upto 2000 characters.
- large - It is a text area type that allows upto 32000 characters.
- rich_text - It is a text area type that allows up to 50000 characters.

Note

The tooltip key only supports both the info_icon value and static_text value.

Sample Input : Field Type - Text Area

Copied{
    "fields": [
        {
            "field_label": "Name",
            "data_type": "textarea",
            "length" : 50000,
            "textarea": {
                "type": "rich_text"
            },
            "tooltip": {
                "name": "static_text",
                "value": "Enter your name"
            },
            "profiles": [
                {
                    "id": "2423488000000015972",
                    "permission_type": "read_write"
                },
                {
                    "id": "2423488000000015975",
                    "permission_type": "read_write"
                }
            ]
        }
    ]
}

Sample Response

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "111112000000067259"
            },
            "message": "field created",
            "status": "success"
        }
    ]
}

"Email" ("data_type": "email")

Note

The tooltip key supports the static_text and info_icon value.

Sample Input: Field Type - Email

Copied{
    "fields": [
        {
            "field_label": "Email address",
            "data_type": "email", // Specify the data type as email*
            "length": 100,
            "tooltip": {
                "name": "static_text",
                "value": "Enter email address"
            },
            "crypt": {
                "mode": "decryption"
            }, 
            "unique": {
                "case_sensitive": false
            },
            "hipaa_compliance_enabled": true,
            "private": {
                "type": "High"
            }
        }
    ]
}

Input JSON

"Picklist Field" ("data_type": "picklist")
"Multi-select Picklist Field" ("data_type": "multiselectpicklist")
"Global PickList Field" ("data_type": "picklist")

For picklist field, the value of data_type should be picklist. For multiselect picklist field, the value of data_type should be multiselectpicklist. Refer to the sample input for more details.

pick_list_valuesJSON array, mandatory
It represents the values or options of the picklist field.
- display_valuestring, mandatory
  The unique display value for the picklist, which will be displayed in the CRM UI.
- actual_valuestring, mandatory
  The unique reference value associated with the particular option.
pick_list_values_sorted_lexicallyBoolean, optional
It represents the sort order preference for the global set values.
Possible values are : false - given order (default value), true - alphabetical order.
enable_colour_codeBoolean, optional
Specify whether to enable color for the picklist options. The default value is false.
global_picklistJSON object, optional (mandatory while associate a global picklist)
Use this key to associate a global picklist to a module.
- idstring, mandatory
  Represents the unique ID of the global picklist. Get your Global Picklist IDs and other related details using the Get Global Picklists API.

Note

The tooltip key for picklist (including global picklist) and multiselect picklist field data types supports only the info_icon value.

Sample Input: Field Type - Picklist and Global Picklist

Copied{
    "fields": [
        {
            "field_label": "Select Region",
            "data_type": "picklist", // Specify the data type as picklist* 
            "tooltip": {
                "name": "info_icon",
                "value": "Select your region here"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "pick_list_values": [
                {
                    "display_value": "East",
                    "actual_value": "IN_East"
                },
                {
                    "display_value": "West",
                    "actual_value": "IN_West"
                },
                {
                    "display_value": "North",
                    "actual_value": "IN_North"
                },
                {
                    "display_value": "South",
                    "actual_value": "IN_South"
                }
            ],
            "pick_list_values_sorted_lexically": true,
            "enable_colour_code": true
        },
     //Associating a Global Picklist below: 
        {
            "field_label": "Source", 
            "data_type": "picklist", // to associate a global picklist, use the data type as "picklist"
            "global_picklist": {
                "id": "2423488000000492003" //ID of the global picklist
            }
        }
    ]
}

Sample Input: Field Type - Multi-select Picklist

Copied{
    "fields": [
        {
            "field_label": "Preferred working days",
            "data_type": "multiselectpicklist", // Specify the data type as multiselectpicklist* 
            //"length": 25,
            "tooltip": {
                "name": "info_icon",
                "value": "Select your region here"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_only"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "hidden"
                }
            ],
            "pick_list_values": [
                {
                    "display_value": "Monday",
                    "actual_value": "1"
                },
                {
                    "display_value": "Tuesday",
                    "actual_value": "2"
                },
                {
                    "display_value": "Wednesday",
                    "actual_value": "3"
                },
                {
                    "display_value": "Thursday",
                    "actual_value": "4"
                },
                {
                    "display_value": "Friday",
                    "actual_value": "5"
                }
            ],
            "pick_list_values_sorted_lexically": true,
            "enable_colour_code": true
        }
    ]
}

Input JSON

Enable history tracking for picklist fields

history_tracking_enabledBoolean, mandatory
You can enable history tracking for a picklist when creating a picklist field. Use this key to enable history tracking for a picklist field.
history_trackingJSON object, optional
Contains the configuration details for tracking the history of a picklist field.
- related_list_namestring, optional
  Specify the name for the related list that displays the picklist field's history in the record detail view as a related list. If not specified, the system auto-generates one based on the field label. The value for related_list_name can have a maximum of 25 characters and cannot include special characters.
- duration_configurationstring, optional
  Specify the unit of time (e.g., days or time) for tracking history.
  Possible values:
  - days (default) - History is tracked by days.
  - time - History is tracked by time.
    - Note: Before specifying the time value, enable the duration customization feature in your organization by contacting support@zohocrm.com.
- followed_fieldsJSON array, optional
  Specify additional fields to track along with the main picklist field for comprehensive change tracking of related fields. Each object in the array must include either the API name or the unique ID of a followed field. Refer to the GET - Fields Metadata API to retrieve field API names and IDs for a module.
  
  For instance, if a sales team tracks the Property Status picklist to monitor how long a property stays in each stage, they can add User Assigned to followed_fields to track which user handled the property at each stage.

Note

In the followed_fields,
- You can select up to 10 fields in total, with a maximum of 5 user fields as followed fields in a module.
- Encrypted fields cannot be specified.

Sample Input: To enable history tracking for picklist values

Copied{
    "fields": [
        {
            "field_label": "Region",
            "data_type": "picklist",
            "pick_list_values": [
                {
                    "display_value": "East",
                    "actual_value": "IN_East"
                },
                {
                    "display_value": "West",
                    "actual_value": "IN_West"
                },
                {
                    "display_value": "North",
                    "actual_value": "IN_North"
                },
                {
                    "display_value": "South",
                    "actual_value": "IN_South"
                }
            ],
            "history_tracking_enabled": true,
            "history_tracking": {
                "related_list_name": "Region history",
                "duration_configuration": "days",
                "followed_fields": [
                    {
                        "api_name": "Owner",
                        "id": "5725767000000002589"
                    }
                ]
            }
        }
    ]
}

Field Types: "Date" ("data_type": "date") and "DateTime" ("data_type": "datetime")

Note

The tooltip key only supports the info_icon value for Date and DateTime fields.

Sample Inputs : Field Types - Date and Date Time

Copied{
    "fields": [
        {
            "field_label": "Date of birth",
            "data_type": "date", // Specify the data type as date* 
            "tooltip": {
                "name": "info_icon",
                "value": "Select date of birth"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_only"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "crypt": {
                "mode": "decryption"
            }
        },
        {
            "field_label": "Time of birth",
            "data_type": "datetime", // Specify the data type as datetime* 
            "tooltip": {
                "name": "info_icon",
                "value": "Select date of birth"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_only"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "crypt": {
                "mode": "decryption"
            }
        }
    ]
}

Sample Response

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067232"
            },
            "message": "field created",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067238"
            },
            "message": "field created",
            "status": "success"
        }
    ]
}

Sample successful response for multiple fields creation in a single API call.

Input JSON

"Integer Field" ("data_type": "integer")

separatorBoolean, optional
Represents whether to display the number in a formatted view for better readability, or not. The number format can be customized for each user in the Personal Settings. The default value is true.

Note

The tooltip key supports both the static_text value and info_icon value.

Sample Input : Field Type - Integer

Copied{
    "fields": [
        {
            "field_label": "Monthly salary",
            "data_type": "integer", // Specify the data type as integer* 
            "length": 9,
            "tooltip": {
                "name": "static_text",
                "value": "Enter salary"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "unique": {
                "case_sensitive": false
            },
            "crypt": {
                "mode": "encryption"
            },
            "separator": true
        }
    ]
}

Input JSON

"Auto Number" ("data_type": "autonumber")

auto_numberJSON object, mandatory
Contains the details of the auto number field.
- start_numberinteger, mandatory
  It specifies the starting number for the auto number sequence.
- prefixstring, optional
  It represents the prefix value to be added to the autonumber field value.
- suffixstring, optional
  It represents the suffix value to be added to the autonumber field value.
_update_existing_recordsBoolean, object
Specify whether the existing auto-number records should be replaced with new auto-numbers of the specified format or not. Default value is false.

Note

The tooltip key for autonumber field supports only the info_icon value.

Sample Input: Field Type - Auto Number

Copied{
    "fields": [
        {
            "field_label": "Employee Identification number",
            "data_type": "autonumber", // Specify the data type as autonumber* 
            "length": 255,
            "tooltip": {
                "name": "info_icon",
                "value": "Your Employee ID"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "auto_number": {
                "start_number": 1000,
                "prefix": "Emp",
                "suffix": "_IN"
            },
            "_update_existing_records": false
        }
    ]
}

Input JSON

"External field" ("data_type": "text")

externalJSON object, optional
Represents whether to mark the field as an external field, where information about the record from a third-party application can be stored. The possible value for the type are: user - A different external ID will be generated for each user, and org - All the users in the organization will have a common external ID. Refer to Set External Field for more information. The key show indicates the field is displayed in the UI.

Note

You can create external fields in calls module from this version.

Sample Input: Field Type: Text (External field)

Copied{
    "fields": [
        {
            "data_type": "text",
            "field_label": "External Field",
            "external": {
                "type": "org",
                "show": true
            }
        }
    ]
}

Input JSON

"Formula" ("data_type": "formula")

formulaJSON object, mandatory
Contains the details of the formula field, including the return type and the expression.
- return_typestring, optional
  Specify the return type for the formula field.
  Possible values:
  double
  currency
  text
  date
  datetime
  boolean
- expressionstring, mandatory
  Specify the formula expression. Please refer to Creating Formula Fields to learn more about formula expressions, and how to draft them.
decimal_placeinteger, optional
The number of decimal places for the formula field. This is valid for double and currency return types. Possible values are from 0 to 9, both inclusive.
number_separatorBoolean, optional
Specify whether to display the field value in formatted view. The default value is true.

Note

The Formula field supports only the info_icon value for the tooltip key.

Sample Input: Field Type: Formula

Copied{
  "fields": [
    {
      "field_label": "Formula Decimal",
      "data_type": "formula",
      "length": "100000000",
      "profiles": [
        {
          "id": "2309216000000015972",
          "permission_type": "read_write"
        }
      ],
     
      "formula": {
        "return_type": "double",
        "expression": "Sqrt(Len(${Email}))"
      },
      "decimal_place": 7,
      "number_separator": true
    }
  ]
}

Input JSON

"Currency" ("data_type": "currency")

currencyJSON object, mandatory
The JSON object containing the currency specific details for the field. Refer to Currency Fields for more information.
- rounding_optionstring, mandatory
  It specifies how the values entered in the currency field should be rounded.
  Possible rounding options:
  - normal - No rounding operations are applied. The value is stored as entered.
  - round_off - Rounds the decimal part to the nearest whole number based on the specified precision.
    For example, for a decimal_value of 2 and precision 2:
    1234.567 rounds off to 1234.57
    1234.123 rounds off to 1234.12
  - round_up - Rounds the decimal part up to the nearest whole number based on the specified precision.
    For example, for a decimal_value of 2 and precision 2:
    1234.567 rounds up to 1234.57
    1234.123 rounds up to 1234.13
  - round_down - Rounds the decimal part down the nearest whole number based on the specified precision.
    For example, for a decimal_value of 2 and precision 2:
    1234.567 rounds down to 1234.56
    1234.123 rounds down to 1234.12
- precisioninteger, optional
  Represents the number of decimal places displayed for the currency value in the user interface. This value should be less than decimal_place
  Example: Currency value: $123.466, the precision value is set to 2, the final currency value will be $123.47. (Note: "rounding_option" : "round_up").
decimal_placeinteger, optional
Defines the maximum numberof decimal places allowed for storing currency values in the field. This value cannot exceed 9. Values exceeding the set decimal_place will be truncated during storage. This means that any decimal places beyond the specified limit will not be saved.

Note

The filterable key is not supported for the formula data type when its return_type is text.
The precision value for currency should be less than the decimal_place.
The tooltip key supports only the info_icon value.
Maximum value for decimal_place is 9.

Sample Input: Field Type: Currency

Copied{
    "fields": [
        {
            "field_label": "Bonus",
            "data_type": "currency", // Specify the data type as currency* 
            "length": 16,
            "tooltip": {
                "name": "info_icon",
                "value": "Bonus Amount"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "crypt": {
                "mode": "encryption"
            },
            "decimal_place": 5,
            "currency": {
                "rounding_option": "round_up",
                "precision": 3
            }
        }
    ]
}

Field Types: Percent, BigInt, Double, Website, and Boolean

Note

The data types Percent, Big Int, Double, Boolean, and Website support both the static_text and info_icon values for the tooltip key.
Ensure that the decimal value is less than the provided length value in the input.

Sample Inputs : Field Types: Percent, BigInt, Double, Website, and Boolean

Copied{
    "fields": [
        {
            "field_label": "Percent marks in qualifying exam",
            "data_type": "percent", // Specify the data type as percent* 
            "length": 5,
            "tooltip": {
                "name": "static_text",
                "value": "Your marks"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ]
        },
        {
            "field_label": "Enrollment number",
            "data_type": "bigint", // Specify the data type as bigint* 
            "length": 18,
            "tooltip": {
                "name": "static_text",
                "value": "Enrollment no."
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "crypt": {
                "mode": "decryption"
            },
            "separator": true
        },
        {
            "field_label": "annualrevenue",
            "data_type": "double", // Specify the data type as double* 
            "length": 16,
            "tooltip": {
                "name": "static_text",
                "value": "annual revenue"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "crypt": {
                "mode": "decryption"
            },
            "separator": true,
            "decimal_place": 9
        },
        {
            "field_label": "Website",
            "data_type": "website", // Specify the data type as website* 
            "length": 450,
            "tooltip": {
                "name": "static_text",
                "value": "Your Website"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ],
            "crypt": {
                "mode": "decryption"
            }
        },
        {
            "field_label": "Prefer to work overseas?",
            "data_type": "boolean", // Specify the data type as boolean* 
            "tooltip": {
                "name": "info_icon",
                "value": "Prefer to work overseas?"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111116000000000423",
                    "permission_type": "read_only"
                }
            ]
        }
    ]
}

A Maximum of 5 fields can be created in a single API call.

Sample Response

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067722"
            },
            "message": "field created",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067728"
            },
            "message": "field created",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067734"
            },
            "message": "field created",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067740"
            },
            "message": "field created",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067761"
            },
            "message": "field created",
            "status": "success"
        }
    ]
}

Input JSON

Field Types: "Rollup Summary" ("data_type": "rollup_summary")

field_labelstring, mandatory
Represents the label of the field.
data_typestring, mandatory
Indicates the type of data for the field
rollup_summaryJSON object, mandatory
This object contains the details for configuring the rollup summary.
- return_typestring, mandatory
  Specifies the type of value returned by the rollup summary.
- expressionJSON object, mandatory
  Defines the calculation expression for the rollup summary.
  - function_parametersarray, mandatory
    An array that holds parameters for the function used in the expression.
    api_namestring, mandatory
    Represents the API name of the field being summarized.
  - criteriaJSON object, mandatory
    Represents filtering criteria for records.
    comparator: Indicates the comparison operator used in this criterion.
    field: Consists of the API name (api_name) of the field used in the criterion.
    value: The specific value used in this criterion.
  - function: Indicates the mathematical function applied to calculate the rollup summary.
- based_on_moduleJSON object, mandatory
  Specifies which module this rollup summary is based on.
- related_listJSON object, mandatory
  Defines which related list to consider for this rollup.

Note

The length of the rollup summary data type depends on the return type of the field
You can create Custom Rollup summary fields through API. You cannot create predefined Rollup summary field through API.

Sample Inputs : Field Types: Rollup Summary

Copied{
    "fields": [
        {
            "field_label": "Total Invoice Amount",
            "data_type": "rollup_summary",
            "rollup_summary": {
                "return_type": "currency",
                "expression": {
                    "function_parameters": [
                        {
                            "api_name": "Grand_Total"
                        }
                    ],
                    "criteria": {
                        "group_operator": "AND",
                        "group": [
                            {
                                "comparator": "equal",
                                "field": {
                                    "api_name": "Billing_Country"
                                },
                                "value": "United States"
                            },
                            {
                                "comparator": "greater_than",
                                "field": {
                                    "api_name": "Invoice_Date"
                                },
                                "value": "2024-01-01"
                            }
                        ]
                    },
                    "function": "SUM"
                },
                "based_on_module": {
                    "api_name": "Invoices"
                },
                "related_list": {
                    "api_name": "Invoices"
                }
            }
        }
    ]
}

Sample Response

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "3602353000000575124"
            },
            "message": "field created",
            "status": "success"
        }
    ]
}

Input JSON

Field Types: "Auto Refresh Formula Field" ("data_type": "formula")

field_labelstring, mandatory
Represents the label of the field.
data_typestring, mandatory
Indicates the type of data for the field.
formulaJSON object, mandatory
This object contains the details for configuring the formula.
- expressionstring, mandatory
  Defines the formula expression.
- return_typestring, mandatory
  Specifies the type of value returned by the formula.
- dynamicboolean, optional
  Indicates whether the formula is Auto Refresh.
- stop_compute_conditionallyboolean, optional
  Indicates whether to stop computation conditionally.
- stop_compute_expressionstring, mandatory if stop_compute_conditionally is true
  Defines the expression that determines when to stop computation.

Note

You can create upto a maximum of two Auto Refresh formula fields for a module

Sample Inputs : Field Types: Auto Refresh Formula Field

Copied{
    "fields": [
        {
            "field_label": "Deal Age",
            "data_type": "formula",
            "formula": {
                "expression": "Datecomp(${Created_Time},Now())",
                "return_type": "double",
                "dynamic": true,
                "stop_compute_conditionally": true,
                "stop_compute_expression": "${Probability}==100"
            }
        }
    ]
}

Sample Response

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "3602353000000570393"
            },
            "message": "field created",
            "status": "success"
        }
    ]
}

Field Types: "File Upload" ("data_type": "fileupload") and "Image Upload" ("data_type": "imageupload")

Note

The data types File Upload and Image Upload support only the info_icon value for the tooltip key.
The length of the file upload data type should either be 1 or 5.
The image upload data type allows for a maximum of 10 images.

Sample Inputs : Field Types: File Upload, and Image Upload

Copied{
    "fields": [
        {
            "field_label": "Upload Files",
            "data_type": "fileupload",    // Specify the data type as fileupload* 
            "length": 5, //"length" : 1 or 5
            "tooltip": {
                "name": "info_icon",
                "value": "Upload Files"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                }
            ]
        },
        {
            "field_label": "Image Upload",
            "data_type": "imageupload",  // Specify the data type as imageupload* 
            "length": 5, // "length" : 1 to 10
            "tooltip": {
                "name": "info_icon",
                "value": "Upload Files"
            },
            "profiles": [
                {
                    "id": "111116000000000421",
                    "permission_type": "read_write"
                }
            ]
        }
    ]
}

Input JSON

"Lookup Field" ("data_type": "lookup")

lookupJSON object, mandatory
Lookup fields allows you to associate records from different modules with your current module. The lookup JSON object contains the details of the field being created.
- modulestring, mandatory
  Specify the module API name of the module to be associated via the lookup field. Use the Modules API to get the module API names.
display_labelstring, mandatory
It represents the display label of the lookup field in the related list.
revalidate_filter_during_editBoolean , optional
Specify whether to revalidate the filters during edit. When the value is set to true, the pre-defined condition with the lookup filter will be checked during record creation and updation.
query_detailsJSON object , optional
Specify the criteria for filtering the records in the lookup field.
- criteriaJSON object , mandatory when the query_details JSON object is specified
  It defines the criteria for filtering records.
- group_operatorstring , optional (it is mandatory to specify when there are more than one condition)
  Specifies the group operator used in the criteria (e.g., AND, OR).
- groupJSON array
  It represents the group of criteria for filtering records.
  - fieldJSON object
    It represents the API name of the field in the target module. Get the list of fields using the GET - Fields Metadata API.
  - comparatorstring
    It represents the comparison operator used in the criterion (e.g., contains and not_equal).
  - valuestring
    It represents the value used in the criterion. Check the sample input section for reference.

Input JSON

"User Lookup" ("data_type": "userlookup")

sharing_propertiesJSON object, optional
Specify if the user has access to the records that the field associates to.
- share_preference_enabledBoolean, mandatory (It is mandatory when the "sharing_properties" JSON object is specified)
  It represents whether share preferences are enabled (true), or disabled (false) for the field.
- share_permissionBoolean, mandatory (It is mandatory when the "sharing_properties" JSON object is specified)
  It represents the sharing permission for the field.
  Possible values:
  - full-access
  - read-write
  - read-only

Note

The Lookup data type supports both the info_icon and static_text values for the tooltip key.
The User Lookup data type supports only the info_icon value for the tooltip key.
You can create fields in a subform module using the Create Custom Field API. Use the API name of the respective subform module.

Sample Input : Field Types - Lookup, and User Lookup

Copied{
    "fields": [
        {
            "field_label": "Contact Lookup",
            "data_type": "lookup",   // Specify the data type as lookup* 
            "tooltip": {
                "name": "static_text",
                "value": "Linked Lead"
            },
            "lookup": {
                "module": {
                    "id": "111116000000002399",
                    "api_name": "Contacts"
                },
                "display_label": "Contact Lookup",
                "revalidate_filter_during_edit": true,
                "query_details": {
                    "criteria": {
                        "group_operator": "AND",
                        "group": [
                            {
                                "field": {
                                    "api_name": "Employee_Identification_number"
                                },
                                "comparator": "contains",
                                "value": "Emp1000_IN"
                            },
                            {
                                "field": {
                                    "api_name": "Lead_Source"
                                },
                                "comparator": "equal",
                                "value": [
                                    "Advertisement",
                                    "OnlineStore",
                                    "Partner"
                                ]
                            },
                            {
                                "field": {
                                    "api_name": "Phone"
                                },
                                "comparator": "contains",
                                "value": "91"
                            }
                        ]
                    }
                }
            }
        },
        {
            "field_label": "UserLink",
            "data_type": "userlookup",  // Specify the data type as userlookup* 
            "tooltip": {
                "name": "info_icon",
                "value": "Linked user"
            },
            "lookup": {
                "revalidate_filter_during_edit": true,
                "query_details": {
                    "criteria": {
                        "group_operator": "AND",
                        "group": [
                            {
                                "field": {
                                    "api_name": "city"
                                },
                                "comparator": "equal",
                                "value": "Chennai"
                            },
                            {
                                "field": {
                                    "api_name": "country"
                                },
                                "comparator": "equal",
                                "value": [
                                    "India",
                                    "China",
                                    "Japan"
                                ]
                            },
                            {
                                "field": {
                                    "api_name": "mobile"
                                },
                                "comparator": "contains",
                                "value": "91"
                            },
                            {
                                "field": {
                                    "api_name": "email"
                                },
                                "comparator": "contains",
                                "value": "gmail"
                            }
                        ]
                    }
                }
            },
            "sharing_properties": {
                "share_preference_enabled": true,
                "share_permission": "read-only"
            }
        }
    ]
}

Input JSON

"Multi-select Lookup Field" ("data_type": "multiselectlookup")

multiselectlookupJSON object, mandatory
Specify the linking details between the current module (the module mentioned in the URL parameter) and another module using this key.
- connected_detailsJSON object, mandatory
  Contains details about the module you want to connect the current module with.
  - moduleJSON object, mandatory
    Specify the module API name you want to link the current module with. Example: Creating connection from Leads module( mentioned in the URL) to the Contacts module.
    - api_namestring, mandatory
      Specify the API name of the module you want to link the current module with.
      Use the GET - Modules Metadata API to retrieve module API names available in your org.
  - fieldJSON object, mandatory
    When connecting a module, the system creates a new lookup field in the connected module for the current module (specified in the URL). Use this key to specify a field label in the connected module.
    - field_labelstring, mandatory
      Specify the field label for the current module in the connected module.
- linking_detailsJSON object, mandatory
  When creating a multi-select lookup field, the system creates a separate module for both the connected modules, which contains their common details.
  - moduleJSON object, mandatory
    By default, the system will create a linking module for both the connected modules when you create a multi-select lookup field. Specify a field label for the linking module.
    - plural_labelstring, mandatory
      Specify a plural label for the linking module.

Sample Input : Field Type - Multi-select lookup

Copied{
    "fields": [
        {
            "field_label": "SelectContact",
            "data_type": "multiselectlookup",
            "multiselectlookup": {
                "connected_details": {
                    "module": {
                        "api_name": "Contacts"
                    },
                    "field": {
                        "field_label": "LeadSelect"
                    }
                },
                "linking_details": {
                    "module": {
                        "plural_label": "LeadOneXContact"
                    }
                }
            }
        }
    ]
}

Input JSON

"Multi-user Lookup Field" ("data_type": "multiuserlookup")

fieldsJSON object, mandatory
Contains details of the multi-user lookup field.
- field_labelstring, mandatory
  Represents the field label of the multi-user lookup field being created.
- data_typestring, mandatory
  Represents the data type of the multi-user lookup field being created.

Note

When you create a multi-user lookup field in a module, the field created is automatically linked to the "Users" module.

Sample Input : Field Type - Mulit-user lookup

Copied{
    "fields": [
        {
            "field_label": "MultiUserLookup",
            "data_type": "multiuserlookup"
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
- Given data seems to be invalid
- The given profile ID seems to be invalid
Resoutions:
- Specify a valid data in the input. Please refer above to the Input JSON section.
- Specify a valid profile ID.
DEPENDENT_MISMATCHHTTP 400
- The given length value seems to be invalid.
- The dependent fields seems to be invalid or missing
Resolutions:
- The value given in the length attribute is invalid, or the value is larger than the actual limit. Please refer to the Field Types: Data Types and Length Limits to know more about the limits.
- Specify all required valid dependent fields along with their corresponding values.
LIMIT_EXCEEDEDHTTP 400
The field has reached its maximum creation limit
Resolution:
You have already created the maximum possible custom fields. Please refer to feature-wise comparison of Zoho CRM Editions to know about the limits in detail.
DEPENDENT_FIELD_MISSINGHTTP 400
One or more dependent fields are missing
Resolution: Specify all the dependent fields in the input body. Please refer above to Input JSON section.
EXPECTED_FIELD_MISSINGHTTP 404
One or more expected fields missing
Resolution: Specify the dependent keys of a field. Refer above to the Input JSON section.
AMBIGUITY_DURING_PROCESSINGHTTP 400
- The ID given in the request body does not belong to the respective module which you are trying to create.
- Cannot provide both picklist options and global set
Resolutions:
- Specify the required field with its valid module API name and ID.
- Please specify the global picklist JSON object. You cannot simultaneously provide both the picklist options JSON array and the global picklist JSON object.
EXPECTED_DEPENDENT_FIELD_MISSINGHTTP 400
Either global_picklist or picklist values is expected
Resolution:
Provide dependent fields to create a picklist or global picklist field in a layout. Refer to the Create Custom Field API for more information.
DUPLICATE_DATAHTTP 400
- Duplicate field label
- Duplicate display_value has been found among the picklist options
- Duplicate API name has been found for a field creation
Resolutions:
- The field label seems to be a duplicate. Specify a unique field label.
- One or more picklist option values have been found to be the same. Please specify a unique display value.
- Specify a unique API name for a field.
MANDATORY_NOT_FOUNDHTTP 400
Required fields not found
Resolution: One or more mandatory fields are missing for the fields you are trying to create. Please refer above to the Input JSON section.
RESERVED_KEYWORD_NOT_ALLOWEDHTTP 400
System-defined keywords not allowed in the API name
Resolution: Specify a non-system-defined keyword for the API name.
NOT_ALLOWEDHTTP 400
The filterable key is not allowed for the field data type you create.
Resolution: Specify the filterable key only for the supported data types. The following data types do not support the filterable key: textarea, imageupload, and fileupload.
REQUIRED_PARAM_MISSINGHTTP 400
Required parameter is missing
Resolution: Please specify the module parameter and its corresponding value.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to the Endpoints section.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to create custom fields. Create a new token with valid scope. Refer to Scope section.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
NOT_SUPPORTEDHTTP 403
Encryptions is not supported for the requested data type
Resolution:
The requested field type is not supported for the crypt key. Please specify the allowed field data types. Please refer the crypt key in the above Input JSON section to know the allowed field data types.
INVALID_URL_PATTERNHTTP 404
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 the Request URL section.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "fields": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067321"
            },
            "message": "field created",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "111116000000067241"
            },
            "message": "field created",
            "status": "success"
        }
    ]
}

Create Custom Fields

Purpose

Endpoints

Request Details

Request URL

Header

Scope

Parameters

Sample Request

Input JSON

Field Types: Data Types and Length Limits

Sample Input : Field Type - Text

Sample Response

Input JSON

"Text Area" ("data_type": "textarea")

Sample Input : Field Type - Text Area

Sample Response

"Email" ("data_type": "email")

Sample Input: Field Type - Email

Input JSON

"Picklist Field" ("data_type": "picklist")"Multi-select Picklist Field" ("data_type": "multiselectpicklist")"Global PickList Field" ("data_type": "picklist")

Sample Input: Field Type - Picklist and Global Picklist

Sample Input: Field Type - Multi-select Picklist

Input JSON

Enable history tracking for picklist fields

Sample Input: To enable history tracking for picklist values

Field Types: "Date" ("data_type": "date") and "DateTime" ("data_type": "datetime")

Sample Inputs : Field Types - Date and Date Time

Sample Response

Input JSON

"Integer Field" ("data_type": "integer")

Sample Input : Field Type - Integer

Input JSON

"Auto Number" ("data_type": "autonumber")

Sample Input: Field Type - Auto Number

Input JSON

"External field" ("data_type": "text")

Sample Input: Field Type: Text (External field)

Input JSON

"Formula" ("data_type": "formula")

Sample Input: Field Type: Formula

Input JSON

"Currency" ("data_type": "currency")

Sample Input: Field Type: Currency

Field Types: Percent, BigInt, Double, Website, and Boolean

Sample Inputs : Field Types: Percent, BigInt, Double, Website, and Boolean

Sample Response

Input JSON

Field Types: "Rollup Summary" ("data_type": "rollup_summary")

Sample Inputs : Field Types: Rollup Summary

Sample Response

Input JSON

Field Types: "Auto Refresh Formula Field" ("data_type": "formula")

Sample Inputs : Field Types: Auto Refresh Formula Field

Sample Response

Field Types: "File Upload" ("data_type": "fileupload") and "Image Upload" ("data_type": "imageupload")

Sample Inputs : Field Types: File Upload, and Image Upload

Input JSON

"Lookup Field" ("data_type": "lookup")

Input JSON

"User Lookup" ("data_type": "userlookup")

Sample Input : Field Types - Lookup, and User Lookup

Input JSON

"Multi-select Lookup Field" ("data_type": "multiselectlookup")

Sample Input : Field Type - Multi-select lookup

Input JSON

"Multi-user Lookup Field" ("data_type": "multiuserlookup")

Sample Input : Field Type - Mulit-user lookup

Possible Errors

Sample Response

"Picklist Field" ("data_type": "picklist")
"Multi-select Picklist Field" ("data_type": "multiselectpicklist")
"Global PickList Field" ("data_type": "picklist")