Skip to product menu
close
EXPLORE ALL PRODUCTS

Sales

 
CRM

Comprehensive CRM platform for customer-facing teams.

CRM
 
Bigin

Simple CRM for small businesses moving from spreadsheets.

Bigin
 
Forms

Build online forms for every business need.

Forms
 
SalesIQ

Live chat app to engage and convert website visitors.

SalesIQ
 
Bookings

Appointment scheduling app for consultations with customers.

Bookings
 
Sign

Digital signature app for businesses.

Sign
 
RouteIQ

Comprehensive sales map visualization and optimal route planning solution.

RouteIQ
 
Thrive

Complete loyalty and affiliate management platform.

Thrive
 
Suites
CRM Plus

Unified platform to deliver top-notch customer experience.

CRM Plus

Marketing

 
Social

All-in-one social media management software.

Social
 
Campaigns

Create, send, and track targeted email campaigns that drive sales.

Campaigns
 
Forms

Build online forms for every business need.

Forms
 
Survey

Design surveys to reach and interact with your audience.

Survey
 
Sites

Online website builder with extensive customisation options.

Sites
 
PageSense

Website conversion optimization and personalisation platform.

PageSense
 
Backstage

End-to-end event management software.

Backstage
 
Webinar

Webinar platform for webcasting online webinars.

Webinar
 
Marketing Automation

All-in-one marketing automation software.

Marketing Automation
 
LandingPage

Smart landing page builder to increase conversion rates

LandingPage
 
SalesIQ

Live chat app to engage and convert website visitors.

SalesIQ
 
Sign

Digital signature app for businesses.

Sign
 
Thrive

Complete loyalty and affiliate management platform.

Thrive
 
NEW
LeadChain

Sync, manage, and convert leads across channels seamlessly.

LeadChain
 
NEW
CommunitySpaces

Online community platform for individuals and businesses to grow their network and brand.

CommunitySpaces
 
Suites
Marketing Plus

Unified marketing platform for marketing teams.

Marketing Plus

Commerce

 
Commerce

eCommerce platform to manage and market your online store.

Commerce

Service

 
Desk

Helpdesk software to deliver great customer support.

Desk
 
Assist

Remote support and unattended remote access software.

Assist
 
Lens

Interactive remote assistance software with augmented reality.

Lens
 
FSM

End-to-end field service management platform for service businesses.

FSM
 
SalesIQ

Live chat app to engage and convert website visitors.

SalesIQ
 
Bookings

Appointment scheduling app for consultations with customers.

Bookings
 
Suites
Service Plus

Unified platform for customer service and support teams.

Service Plus

Finance

 
Books

Powerful accounting platform for growing businesses.

Books
 
FREE
Invoice

100% Free invoicing solution.

Invoice
 
Expense

Effortless expense reporting platform.

Expense
 
Inventory

Powerful stock management and inventory control software.

Inventory
 
Billing

End-to-end billing solution for your business.

Billing
 
Checkout

Collect payments online with custom branded pages.

Checkout
 
Practice

Practice management software for accounting firms.

Practice
 
Sign

Digital signature app for businesses.

Sign
 
Commerce

eCommerce platform to manage and market your online store.

Commerce
 
Suites
Finance Plus

All-in-one suite to manage your operations and finances.

Finance Plus

Email and Collaboration

 
Mail

Secure email service for teams of all sizes.

Mail
 
Meeting

Online meeting software for all your video conferencing & webinar needs.

Meeting
 
Writer

Word processor for focused writing and discussions.

Writer
 
Sheet

Spreadsheet software for collaborative teams.

Sheet
 
Show

Create, edit, and share slides with a sleek presentation app.

Show
 
Notebook

Beautiful home for all your notes.

Notebook
 
Cliq

Stay in touch with teams no matter where you are.

Cliq
 
Connect

Employee experience platform to communicate, engage, and build positive employee relations.

Connect
 
Bookings

Appointment scheduling app for consultations with customers.

Bookings
 
TeamInbox

Shared inboxes for teams.

TeamInbox
 
WorkDrive

Online file management for teams.

WorkDrive
 
Sign

Digital signature app for businesses.

Sign
 
Office Suite

Powerful collaborative work platform for teams.

Office Suite
 
Office Integrator

Built in document editors for web apps.

Office Integrator
 
ZeptoMail

Secure and reliable transactional email sending service.

ZeptoMail
 
Calendar

Online business calendar to manage events and schedule appointments.

Calendar
 
Learn

Knowledge and learning management platform.

Learn
 
ToDo

Collaborative task management for individuals and teams.

ToDo
 
FREE
PDF Editor

Collaborative online PDF editing tool.

PDF Editor
 
Suites
Workplace

Application suite built to improve team productivity and collaboration.

Workplace

Human Resources

 
People

Organize, automate, and simplify your HR processes.

People
 
Recruit

Intuitive recruiting platform built to provide hiring solutions.

Recruit
 
Expense

Effortless expense reporting platform.

Expense
 
Workerly

Manage temporary staffing with an employee scheduling solution.

Workerly
 
Shifts

Employee scheduling and time tracking app.

Shifts
 
Sign

Digital signature app for businesses.

Sign
 
Suites
People Plus

Comprehensive HR platform for seamless employee experiences.

People Plus

Security and IT Management

 
Creator

Build custom apps to simplify business processes.

Creator
 
Directory

Workforce identity and access management solution for cloud businesses.

Directory
 
FREE
OneAuth

Secure multi-factor authenticator (MFA) for all your online accounts.

OneAuth
 
Vault

Online password manager for teams.

Vault
 
Catalyst

Pro-code platform to build and deploy your apps.

Catalyst
 
Toolkit

Complete resource for any admin-related lookup queries.

Toolkit
 
Lens

Interactive remote assistance software with augmented reality.

Lens
 
Assist

Remote support and unattended remote access software.

Assist

BI and Analytics

 
Analytics

Modern self-service BI and analytics platform.

Analytics
 
Embedded BI

Embedded analytics and white label BI solutions, tailored for your needs.

Embedded BI
 
DataPrep

AI-powered data preparation service for your data-driven organization.

DataPrep
 
NEW
IoT

Harnessing IoT analytics for real-time operational intelligence.

IoT

Project Management

 
Projects

Manage, track, and collaborate on projects with teams.

Projects
 
Sprints

Planning and tracking tool for scrum teams.

Sprints
 
BugTracker

Automatic bug tracking software for managing bugs.

BugTracker
 
Suites
Projects Plus

Unified project management platform for intelligent, data-driven work.

Projects Plus

Developer Platforms

 
Creator

Build custom apps to simplify business processes.

Creator
 
Flow

Automate business workflows by creating smart integrations.

Flow
 
Catalyst

Pro-code platform to build and deploy your apps.

Catalyst
 
Office Integrator

Built in document editors for web apps.

Office Integrator
 
ZeptoMail

Secure and reliable transactional email sending service.

ZeptoMail
 
NEW
Apptics

Application analytics for all apps.

Apptics
 
Embedded BI

Embedded analytics and white label BI solutions, tailored for your needs.

Embedded BI
 
NEW
IoT

Build, deploy, and scale IoT solutions for connected businesses.

IoT
 
DataPrep

AI-powered data preparation service for your data-driven organization.

DataPrep

IoT

 
NEW
IoT

Low-code IoT platform and solutions for connected businesses.

IoT
 
CRM Plus

Unified platform to deliver top-notch customer experience.

Try now
CRM Plus
 
Service Plus

Unified platform for customer service and support teams.

Try now
Service Plus
 
Finance Plus

All-in-one suite to manage your operations and finances.

Try now
Finance Plus
 
People Plus

Comprehensive HR platform for seamless employee experiences.

Try now
People Plus
 
Workplace

Application suite built to improve team productivity and collaboration.

Try now
Workplace
 
Marketing Plus

Unified marketing platform for marketing teams.

Try now
Marketing Plus
 
Projects Plus

Unified project management platform for intelligent, data-driven work.

Try now
Projects Plus
 
All-in-one suite

Zoho One

The Operating System for Business

Run your entire business on Zoho with our unified cloud software, designed to help you break down silos between departments and increase organizational efficiency.

TRY ZOHO ONE
Zoho One
Zoho Marketplace

With over 2000 ready-to-use extensions across 40+ categories, connect your favorite business tools with the Zoho products you already use.

EXPLORE MARKETPLACE
Marketplace
Skip to main content

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)

Texttext1 to 255
Text Areatextarea2000 or 32000 or 50000
Emailemail1 to 100
Phonephone1 to 30
Integerinteger1 to 9
Auto Numberautonumber1 to 255
Currencycurrency1 to 16
Percentpercent1 to 5
BigIntbigint1 to 18
Doubledouble1 to 18
Websitewebsite1 to 450
File Uploadfileupload1 or 5
Image Uploadimageupload1 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"
                }
            ]
        }
    ]
}

Show full

Show less

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

Show full

Show less

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

Show full

Show less

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

Show full

Show less

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

Show full

Show less

Sample Response

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

Show full

Show less

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

Show full

Show less

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

Show full

Show less

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

Show full

Show less

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

Show full

Show less

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