Kaizen #1 - Fields in CRM #API

Kaizen #1 - Fields in CRM #API

Hey everyone, welcome to the Zoho CRM Developer Community series. The series is named 'Kaizen', meaning continuous improvement. Through these series of posts, we aim at resolving all the frequently asked questions, common hurdles, and discuss the best practices to be followed by the CRM developer community.

We have five different streams under kaizen. Each one is related to a different stream of CRM developmentAPI v2.0, Functions, SDK, Mobile Development, and Widgets. Every post will be tagged under one of these streams with a hashtag(#). Based on your area of expertise, you can choose to follow any of them. 

So, here is the drill: 
  • We will drop a few eggs of knowledge on a most discussed topic in our developer community forum, and tag it under one of the five streams. 
  • As always, you can keep the questions coming and kick start a productive discussion. 
  • The routine iterates every Friday.
Since this is our first forum post, we decided to start with something basic.

The problem


In ZohoCRM, data is organized into fields (individual chunks of data). For instance, 'First Name', 'Email', and so on. 

As we are all aware, there are multiple field types available in Zoho CRM. Each field type has its limitations on the type and length of data that can be stored in that particular field. It is essential to adhere to these restrictions while inserting, updating, upserting data. If not, it can lead to unsuccessful requests and errors. 

What you will learn from this post


In this post, we are going to walk you through the following, to give you a better idea of different field types in Zoho CRM and their role while inserting, updating, and upserting records. 

  • Different types of fields in Zoho CRM
  • Details about each field type - [ data type, limitations (what type of characters are accepted), size ]
  • Inserting records in Zoho CRM- with emphasis on fields [System-defined mandatory fields for each module]
  • A few use-cases on inserting records in Zoho CRM

a. Different types of fields in Zoho CRM


Fields are used to store data in a structured way in Zoho CRM. 

Based on how the data is stored, they are of two types:


(i) Read-only fields - For these fields, data is system generated. For instance, "created_by", "created_time", "last_activity_time", "modified_by", "modified_time", and so on. Users cannot modify these fields.
 
(ii) Read/Write fields - For these fields, data is set by the user. For instance, "first_name", "last_name", "email", and so on. 

For custom fields and default fields, you can update this property by editing the field-permissions in the set-up screen in UI. You set the fields to be either read-only, read/write, or hidden.

Note that this property cannot be altered for system-defined mandatory and custom mandatory fields.

b. Details about each field type


Just like data types available in multiple programming languages, there are multiple field types in Zoho CRM, allowing you to store different types of data about your customers, users, vendors, and so on. For instance, we have 'Single Line' field type where you can store strings, it allows you to store all the alphanumeric and special characters within a length of 255 characters. 

Apart from default fields, Zoho CRM allows you to create custom fields. Knowing about the field types is essential to pick the right kind of field type for your custom field. For instance, a 'phone' field type would be more appropriate for a custom-field that stores phone numbers than 'single line' type, since phone allows only numeric characters and '+' (to add extensions).

You can find the details about data types and restrictions about each field type in 'modules and fields' section in Zoho CRM UI. Through API, you can get the data type of the fields in a module using meta data API

URL

​​​{{api-domain-URL}}/crm/v2/settings?fields?module={module_API_name}


The following table gives you specific details about each field type in Zoho CRM and their limitations. 
The JSON type and the data type of the field-types are extracted from fields meta data API. 

JSON type - tells in what format the field should be passed in request-body/ will be received in response
data type - tells the type of data that can be stored in a field with that particular field-type


Field-type
Limitations
Example
Single Line
JSON type - string
data type - text
Accepts up to 255 characters.

Accepts alphanumeric and special characters.
"Last_name": "Mike O'Leary"


Multi-Line
JSON type - string
data type - textarea


Small - accepts up to 2000 characters.

Large - accepts up to 32000 characters.


You will not be able to use this field to create custom views, reports or other filters.



Accepts alphanumeric and special characters.




"Description": "This is a sample description"


Email
JSON type - string
data type - email


Accepts valid email IDs.

"Email": "merced@zylker.com"


Phone
JSON type - string
data type - phone


Accepts up to 30 characters. This limit may vary based on the value configured in 'Number of characters allowed' in the properties pop-up of the field, in UI.

Accepts only numeric characters and '+' (to add extensions).

"Phone": "9800000099"


Picklist
JSON type - string
data type - picklist


You can either pass an existing pick list value or add a new one. 


The pick list value accepts all alphanumeric and special characters.

"Industry": "automobile"


Multiselect pick list
JSON type - jsonarray
data type - multiselectpicklist


You can either pass existing pick list values or add a new one.


The pick list value accepts all alphanumeric and special characters.


"Courses opted": [
                               "Analytics", 
                                "Big data"
                                           ]



Date
JSON type - string 
data type - date


Accepts date in yyyy-MM-dd format.

"Date": "2019-08-28"


Date/time
JSON type - string
data type - datetime



Accepts date and time in yyyy-MM-ddTHH:mm:ss±HH:mm
ISO 8601 format.


"Date_Time": "2019-08-28T20:32:36+05:30"


Number
JSON type - integer
data type - integer


Accepts numbers up to 9 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.

Accepts only numeric values.

"No. of employees": "350"


Currency
JSON type - double
data type - currency


Before decimal point - accepts numbers up to 16 digits.  This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.


After decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal paces' in the properties pop-up of the field, in UI.

Accepts only numeric values.

"Annual Revenue": 250000.90


Decimal
JSON type - double
data type - double


Before decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.


After decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal places' in the properties pop-up of the field, in UI.

Accepts only numeric values.

"Decimal_1": 250000.50


Percent
JSON type - double
data type - double


Accepts numbers up to 5 digits.

Accepts only numeric values.

"Percentage": 25


Long integer
JSON type - string
data type - bigint


Accepts numbers up to 18 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.


Accepts only numeric values.

"EAN_Code":"0012345600012"


Checkbox
JSON type - boolean
data type - boolean


Accepts only Boolean values(true,false).

"Email_Opt_Out": true


URL
JSON type - string
data type - website


Accepts valid URLs.

"URL": "https://www.zylker.com"


Lookup
JSON type - jsonobject
data type - lookup


Accepts unique ID of the record, which you can get through get records API.


"Owner":
  {
  "id":"4150868000000623001"
  }



User
data type - userlookup


This is a default look-up field to users in Zoho CRM.


"User":
  {
  "User_Name":"Patricia Boyle",
  "id":"4150868000000623001"
  }




C. Inserting Records in Zoho CRM

Now that we have covered different field types and details about each field type, let us move on to inserting records in Zoho CRM. 

System-defined mandatory fields for each module

While inserting records there are a few system-defined mandatory fields that you need to mention. Inorder to successfully insert records in Zoho CRM, make sure you enter user-defined mandatory fields too.

The following table gives you information about the system-defined mandatory fields and their field type in Zoho CRM:

Module
System-defined mandatory field
Leads
"Last_Name" - Single Line
Contacts
"Last_Name" - Single Line
Accounts
"Account_Name" - Single Line
Deals
"Deal_Name"- Single Line
"Stage" - Picklist
Tasks
"Subject" - Multi Line
Calls
"Subject" - Multi Line
"Call_Type" - Picklist
"Call_Start_Time" - Date/Time
"Call_Duration" - Single Line
Events
"Event_Title"- Single Line
"Start_DateTime" - Date/Time
"End_DateTime" - Date/Time
Products
"Product_Name" - Single Line
Quotes
"Subject"- Single Line
"Product_Details" - Product Line Item
Invoices
"Subject"- Single Line
"Product_Details" - Product Line Item
Campaigns
"Campaign_Name" - Single Line 
Vendors
"Vendor_Name"- Single Line
Price Books
"Price_Book_Name"- Single Line
"Pricing_Details"- JSON Array with "from_range", "to_range", "discount"
Cases
"Case_Origin" - Picklist
"Status"- Picklist
"Subject" - Single Line
Solutions
"Solution_Title"- Single Line
Purchase Orders
"Subject"- Single Line
"Vendor_Name"- Lookup
"Product_Details" - Product Line Item
Sales Orders
"Subject"-  Single Line
"Product_Details" - Product Line Item 


d. A few use-cases on inserting records in Zoho CRM

A few special cases while inserting records in Zoho CRM are as follows:

  • Product Line Item
  • Reminder
  • Repeat
  • Pricing_Details
  • What_ID, Who_ID
  • Participants

Every Zoho CRM API request body to insert, update, or upsert records should be given in the JSON format. To know the format for each of the above mentioned special cases, refer to our API guide.


Next 'Kaizen' - OAuth2.0 and Self Client #API





















    Access your files securely from anywhere

        Zoho Developer Community







                                  Zoho Desk Resources

                                  • Desk Community Learning Series


                                  • Digest


                                  • Functions


                                  • Meetups


                                  • Kbase


                                  • Resources


                                  • Glossary


                                  • Desk Marketplace


                                  • MVP Corner


                                  • Word of the Day



                                      Zoho Marketing Automation


                                              Manage your brands on social media



                                                    Zoho TeamInbox Resources

                                                      Zoho DataPrep Resources



                                                        Zoho CRM Plus Resources

                                                          Zoho Books Resources


                                                            Zoho Subscriptions Resources

                                                              Zoho Projects Resources


                                                                Zoho Sprints Resources


                                                                  Qntrl Resources


                                                                    Zoho Creator Resources



                                                                        Zoho Campaigns Resources


                                                                          Zoho CRM Resources

                                                                          • CRM Community Learning Series

                                                                            CRM Community Learning Series


                                                                          • Kaizen

                                                                            Kaizen

                                                                          • Functions

                                                                            Functions

                                                                          • Meetups

                                                                            Meetups

                                                                          • Kbase

                                                                            Kbase

                                                                          • Resources

                                                                            Resources

                                                                          • Digest

                                                                            Digest

                                                                          • CRM Marketplace

                                                                            CRM Marketplace

                                                                          • MVP Corner

                                                                            MVP Corner





                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now