Create Custom Fields

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.

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 an info icon tooltip. 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:

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.

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

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. 

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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

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

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.

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.

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.