Update Custom Fields

Purpose

To update custom fields in your Zoho CRM.

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

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

Sample Request to update a single field

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

Parameter

modulestring, mandatory
Specify the module in which you want to update custom fields, such as Leads or Contacts.

Notes

Please note that all the field types and cases explained in the Create Custom Field help document are supported by Update Custom Field API.
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" }
In picklist data type, only adding options is possible. Neither updating nor deleting 'pick_list_values' options is allowed. Additionally, in picklist data type, the addition of options in 'pick_list_values': [{option - 1}, {option - 2}, ...] is allowed.
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 Input to update "Picklist" Data Type

Copied{
    "fields": [
        {
            "profiles": [
                {
                    "id": "111112000000000421",
                    "permission_type": "read_write"
                },
                {
                    "id": "111112000000000423",
                    "permission_type": "read_write" //updating the permission_type
                }
            ],
            "pick_list_values": [
                {
                    "display_value": "South_West",
                    "actual_value": "IN_South_West"
                },
                {
                    "display_value": "North_East",
                    "actual_value": "IN_North_East",
                } //Adding options to an existing picklist         
            ]
        }
    ]
}

Sample Response

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

Sample Request to update multiple fields

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

Input JSON Keys

idstring, mandatory
It represents the ID of the field type you want to update.

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"
            }
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
- The ID given seems to be invalid
- Special characters have been found in the field label
- Invalid formula expression
Resolutions:
- Specify a valid field ID.
- The field label does not support special characters.
- Specify a valid formula expression.
NOT_ALLOWEDHTTP 400
- Lookup module cannot be updated
- Formula field does not support updating the return type
- Private is not allowed
- Unique case is not allowed
Resolutions:
- Once the lookup module is associated with the field, it cannot be updated.
- Updating the return type in the formula field is not supported.
- Enable the privacy setting and update the private value.
- 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
- Duplicate display_value has been found among the picklist options
- Duplicate API name has been found for a field creation
- Duplicate data has been found
Resolutions:
- The field label seems to be a duplicate of another field's label. 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.
- Specify a unique value to update the field.
MANDATORY_NOT_FOUNDHTTP 400
Required fields not found
Resolution:
Specify the require fields to update. Refer to this help API documentto know the mandatory fields.
REQUIRED_PARAM_MISSINGHTTP 400
Required paramter is missing
Resolution: Please specify the modules parameter and its corresponding value.
INVALID_DATAHTTP 400
The job_id is invalid.
Resolution: Specify a valid job 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 seems to be invalid or the value is larger than the actual limit.
- Specify the valid dependent keys along with their corresponding valid values.
Refer to this help API document 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 scope section above.
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": "111112000000069633"
            },
            "message": "field updated",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "111112000000069633"
            },
            "message": "field updated",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "111111000000166083"
            },
            "message": "field updated",
            "status": "success"
        }
    ]
}