Update Custom Fields

Purpose

To update custom fields in your Zoho CRM account.

Endpoints

PATCH /settings/fields?module={module_API_name}
PATCH /settings/fields/{field_ID}?module={module_API_name}

Request Details

Request URL

To update multiple fields:

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

To update a single field:

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

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Sample request to update a single field

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

Parameters

modulestring, mandatory
Specify the module in which you want to update 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.

Note

All the field types and cases explained in the Create Custom Field API help document are supported by the Update Custom Field API.
Retrieve field IDs using the GET - Fields Metadata API.
The field label for system-defined fields cannot be updated.
A maximum of five field can be updated in a single call.
Conversion of one field type to another is not possible.
External attribute cannot be updated.
In text area data type:
- The length value cannot be updated.
- The type value cannot be updated to another type, for example, from small to rich_text.
  Sample: "textarea" : { "type": "small" }
The API name of a field can only be changed in the UI.
The HIPAA attribute can be updated if the particular module has HIPAA field allowed, and privacy settings are enabled.

Sample input to update to "Text" data type

Copied{
    "fields": [
        {
            "length": 200, //updating the value of length
            "unique": {
                "case_sensitive": false,
                "_disable": null //marking the field is not a unique key.
            }
        }
    ]
}

Sample response

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

Input JSON

idstring, mandatory
It represents the ID of the field type you want to update. Retrieve field IDs using the GET - Fields Metadata API.

Sample request to update multiple fields

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

Sample input to update multiple fields

Copied{
    "fields": [
        {
            "id": "111112000000069633",  //Field Type: Lookup
            "lookup": {
                "query_details": {
                    "criteria": {
                        "field": {
                            "api_name": "Email"
                        },
                        "comparator": "ends_with",
                        "value": "@zohocorp.com"
                    }
                }
            }
        },
        {
            "id": "111112000000070141", //Field Type: Currency
            "currency": {
                "rounding_option": "normal",
                "precision": 2
            }
        },
        {
            "id": "111111000000166083", //Field Type : User Lookup
            "sharing_properties": {
                "share_preference_enabled": true,
                "share_permission": "full-access"
            }
        }
    ]
}

Input JSON Keys

Updating the picklist ("datatype" : "picklist") field

The following keys are mandatory to update a picklist field's option.

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.

Note

The display_value field is mandatory when updating an option in a picklist field.
Use the actual_value or unique ID of a picklist option to update its display value.
To remove an option from a picklist, use the Update Custom Layout API. Refer to the Sample input to mark picklist options as unused section.

Sample request to update the "picklist" datatype

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

Sample input to add a new option to the picklist field

Copied{
    "fields": [
        {
            "pick_list_values": [
                {
                    "display_value": "North_East",
                    "actual_value": "IN_North_East",
                } //Adding options to an existing picklist         
            ]
        }
    ]
}

Sample input to update existing picklist data

Copied{
    "fields": [
        {
            "profiles": [
               
                {
                    "id": "5725767000000026011",
                    "permission_type": "read_write" //updating the permission_type
                }
            ],
           "pick_list_values": [
                {
                     "display_value": "East Zone East Zone", // updating the display value
                    "actual_value": "IN_EastZone",
                    "id": "5725767000003489002"
                }
            ]
        }
    ]
}

Updating rollup summary ("datatype" : "rollup_summary") field

Note

Inside rollup_summary.expression only the criteria field can be modified.

Sample request to update the "rollup_summary" datatype

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

Sample input

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": "equal",
                                "field": {
                                    "api_name": "Billing_State"
                                },
                                "value": "Massachusetts"
                            } //Adding new condition
                        ]
                    },
                    "function": "SUM"
                },
                "based_on_module": {
                    "api_name": "Invoices"
                },
                "related_list": {
                    "api_name": "Invoices"
                }
            }
        }
    ]
}

Updating dynamic formula ("datatype" : "formula") field

Sample request to update the "formula" datatype

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

Sample Input

Copied{
    "fields": [
        {
            "json_type": "double",
            "field_label": "Deal Age",
            "display_label": "Age of the deal",
            "length": 16,
            "api_name": "Deal_age",
            "data_type": "formula",
            "id": "3602353000000570393",
            "formula": {
                "expression": "Datecomp(${modified_time},Now())",
                "return_type": "double",
                "dynamic": true,
                "stop_compute_conditionally": false
            },
            "decimal_place": 2
        }
    ]
}

Input JOSN

Converting Picklist to Global Picklist

fieldsJSON array, mandatory
Contains details of the picklist field and the global picklist field.
- idstring, mandatory
  Represents the unique ID of the picklist field you want to convert into a global picklist field.
- pick_list_valuesJSON array, optional
  Contains the mapping details between the picklist field values and the global picklist field values.
  - idstring, mandatory
    Represents the ID of a value in the picklist field. Use the GET - Fields Metadata API to retieve all picklist fields ("data_type": "picklist") in a module.
  - _global_picklist_valueJSON object, optional
    Represents the ID of the value in the global picklist field. Use the GET - Get Global Picklists API to retieve all global picklist fields along with their values.
- global_picklistJSON object, mandatory
  Use the GET - Get Global Picklists API to retrieve all global picklist fields available in your organization.

Note

You can map the values from the picklist field to the values in the global picklist field. By default, if you do not map the values, all values in the picklist field will be replaced with the global picklist field's values.
Any records or configurations with existing picklist values will also be replaced by the global picklist field's values.

Sample request to convert a picklist field to a global picklist field

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

Sample Input

Copied{
    "fields": [
        {
            "id": "2276164000002053013", //picklist ID
            "pick_list_values": [
                {
                    "id": "2276164000002053012", //local picklist value's ID
                    "_global_picklist_value": {
                        "id": "2276164000002053039" //global picklist value's ID
                    }
                },
                {
                    "id": "2276164000002053014", 
                    "_global_picklist_value": {
                        "id": "2276164000002053041"
                    }
                }
            ],
            "global_picklist": {
                "api_name": "Market",
                "id": "2276164000002053035"
            }
        }
    ]
}

Input JOSN

Converting a Global Picklist field to a Picklist field

idstring, mandatory
Represents the unique ID of the global picklist field. Use the GET - Global Picklists API to retrieve global picklist field IDs.
global_picklistJSON object, mandatory
Represents the conversion of a global picklist field into a normal picklist field.

Sample request to convert a global picklist field to a picklist field

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

Sample Input

Copied{
    "fields": [
        {
            "id": "5725767000006269064", //unique ID of the Global picklist field
            "global_picklist": null
        }
    ]
}

Sample response

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

Input JSON

Enable or disable history tracking for picklist fields

history_tracking_enabledBoolean, mandatory
You can enable or disable history tracking for an existing picklist in a module. Use this key to enable or disable history tracking for a picklist field.
history_trackingJSON object, optional
Contains the configuration details for tracking the history of the 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, except for the Deals module.
- Deals module,
  - By default, the Deals module tracks the stage history of the Stage picklist field.
  - You can add more followed fields as columns to the existing stage history.
  - You can also change the related list name and add up to six additional followed fields. You can select upto six fields in total, with a maximum of five user fields.
- Encrypted fields cannot be selected as followed fields.

Sample request to disable history tracking for a picklist field

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

Sample input to disable history tracking for a picklist field

Copied{
    "fields": [
        {
            "history_tracking_enabled": false //mandatory field
        }
    ]
}

Sample input to update the existing values in a picklist with enabled history tracking

Copied{
    "fields": [
        {
            "history_tracking_enabled": true, 
            "history_tracking": {
                 "related_list_name": "Region Tracker", //updating the related list name
                "duration_configuration": "time", //updating the value from "days" to. "time"
                "followed_fields": [
                    {
                        "api_name": "Owner", //removing the owner field from the "followed fields" key 
                        "_delete" : null
                    },
                    {
                        "api_name": "Company", //adding the Company field to the "followed fields" key 
                        "id": "5725767000000002591"
                    }
                ]
            }
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
- The ID given seems to be invalid
  Resolution: Specify a valid field ID.
- Special characters have been found in the field label
  Resolution: The field label does not support special characters.
- Invalid formula expression
  Resolution: Specify a valid formula expression.
NOT_ALLOWEDHTTP 400
- Lookup module cannot be updated
  Resolution: Once the lookup module is associated with the field, it cannot be updated.
- Formula field does not support updating the return type
  Resolution: Updating the return type in the formula field is not supported.
- Private is not allowed
  Resolution: Enable the privacy setting and update the private value.
- Unique case is not allowed
  Resolution: The field you are trying to update does not support the unique key.
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.
DUPLICATE_DATAHTTP 400
- Duplicate field label
  Resolution: The field label seems to be a duplicate of another field's label. Specify a unique field label.
- Duplicate display_value has been found among the picklist options
  Resolution: One or more picklist option values have been found to be the same. Please specify a unique display value.
- Duplicate API name has been found for a field creation
  Resolution: Specify a unique API name for a field.
- Duplicate data has been found
  Resolution: Specify a unique value to update the field.
- Invalid data type has been given for the "reference_value" key
  Resolution: The data type for the "reference_value" key is "string".
MANDATORY_NOT_FOUNDHTTP 400
Required fields not found
Resolution: Specify the require fields to update. Refer to the Create Custom Field API to know the mandatory fields.
REQUIRED_PARAM_MISSINGHTTP 400
Required paramter is missing
Resolution: Please specify the modules parameter and its corresponding value.
LIMIT_EXCEEDEDHTTP 400
Too many options have been added to the Stage picklist field in the Deals module
Resolution: You can add up to 220 options to the Stage picklist field in the Deals module.
DEPENDENT_MISMATCHHTTP 400
- The given length value seems to be invalid.
  Resolution: The value given in the length attribute seems to be
- The dependent fields seems to be invalid or missing
  Resolution: Specify the valid dependent keys along with their corresponding valid values.
Refer to the Create Custom Field API to know the dependent fields.
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 above.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to update custom fields. Create a new token with the required scope. Refer to the Scope section to get an exact scope.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
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 above.
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": "5725767000005821005"
            },
            "message": "field updated",
            "status": "success"
        }
    ]
}