Kaizen #64 - External Fields and Records APIs
Hello everyone!
Welcome back to another exciting post in the Kaizen series!
In this post, we will talk about external fields in Zoho CRM and how they are used in Records APIs.
What is an external field?
While you integrate a third-party application, you may want to associate your own primary key in your DB(or an external system) to Zoho CRM's records, and use them in create/update API rather than CRM's "record ID". To meet this requirement, we have introduced external fields.
An external field is a custom single-line field in a module in Zoho CRM that can hold a record's unique ID available in an external system.
This is useful when you want to upsert records to maintain data sync between Zoho CRM and the external system, and also search for records using their external IDs instead of Zoho CRM's record IDs.
External fields negate the need to maintain two unique IDs in your external system.
Types of External Fields
- User-based external fields
User-based external fields allow values to be stored with respect to each user. So, each user can make use of their corresponding external values(say contact1 and contact2) to manipulate CRM records.
When data sync happens between the external system and Zoho CRM, these users can update the corresponding record with their respective external values(contact1 and contact2). For example, consider that two users have saved the same contact with different IDs c1 and c2, respectively in their external systems. When data sync happens with Zoho CRM from these systems, there will be one contact in CRM. But, the users can use their external contact IDs c1 and c2 to update the record in CRM.
Note that the external value for this type is unique to each user. - Org-based external fields
In contrast to user-based external field, for org-based external fields, there is no association between the external ID stored and the user who configured it. Instead, all users can manipulate the CRM records with that same external ID. Consider that you have a native ERP system to manage finances for your org. The employees(users) will deal with the same clients(leads or contacts). When you integrate this external system with Zoho CRM, the lead/contact ID in the external system becomes the external field value in CRM. Now this integration can use this external ID for any data sync and other actions with Zoho CRM.
How to create an external field in CRM?
- Go to Setup > Customization > Modules and Fields > Choose a module.
- Create a single line field and provide a name.
- Click the more options icon and select Edit Properties.
- In the Single Line Properties pop up, specify the field label, and check the Set External Field box.
- Choose the field's visibility and the type of the external field.
- Click Done. Click Save and Close in the module builder.
Note
- The external ID feature is available only from the Enterprise edition and up.
- You can create a single line field of the type "external" only through the UI.
- A module can have a maximum of 10 external fields for the Enterprise edition and 15 for the Ultimate edition.
In this post, we will discuss using external ID fields in create, update, upsert, delete, and search records APIs.
Mandatory Header in the API Requests
X-EXTERNAL: {module_API_name}.{external_field_API_name}
Note that this header is required only when there are references like lookup fields, line items in the inventory modules, subforms, but not when inserting records directly.
Here is an example of creating a contact while adding a value to the external field.
Module: Contacts
External field's API name: External_Contact_ID, Value: externalcontact1
Request URL: https://www.zohoapis.com/crm/v3/Contacts
Input body:
{ "data": [ { "Last_Name": "ext contact 1", "External_Contact_ID":"externalcontact1" } ] } |
Creating records using external values
Associating a lookup record through an external field
Base Module: Contacts
Lookup Module: Accounts
Lookup field's API name in base module: Account_Name
External field's API name in the lookup module: External_Account_ID; Value: externalaccount1
Header: X-EXTERNAL: Contacts.Account_Name.External_Account_ID
Request URL: https://www.zohoapis.com/crm/v3/Contacts
Input body:
{ "data": [ { "Last_Name": "ext contact 2", "Account_Name": { "External_Account_ID": "externalaccount1" } } ] } |
Inserting a subform lookup record through an external field in the associated module
Base Module: Contacts
API name of the subform in the base module: ExternalSubform
API name of the lookup field in the subform: Deal_Lookup
API name of the external field in the lookup module: External_Deal_ID
Header: X-EXTERNAL: Contacts.ExternalSubform.Deal_Lookup.External_Deal_ID
Request URL: https://www.zohoapis.com/crm/v3/Contacts
Input body:
{ "data": [ { "Last_Name": "Contact with a Subform and external Deal lookup", "ExternalSubform": [ { "Deal_Lookup": { "External_Deal_ID": "extDeal1" } } ] } ] } |
Creating an inventory module's record with external fields in the line items
You can create a record in the inventory module by using the external fields and their values in the line items. For example, creating a quote using the external values of the product and the price book in the Quoted_Items line item.
Inventory Module: Quotes
External field's API name in Products: External_Product_ID; Value: extprod1
External field's API name in Price_Books: External_Price_Book_ID; Value: extpricebook1
Header: X-EXTERNAL: Quotes.Quoted_Items.Product_Name.External_Product_ID,Quotes.Quoted_Items.Price_Book_Name.External_Price_Book_ID
Request URL: https://www.zohoapis.com/crm/v3/Quotes
Input body:
{ "data": [ { "Subject": "Quote 1", "Quoted_Items": [ { "Product_Name": { "External_Product_ID": "extprod1" }, "Price_Book": { "External_Price_book_ID": "extpricebook1" }, "quantity": 100 } ] } ] } |
Inserting an Event and associating the What_Id through an external field
When you insert an event related to an account, the What_Id takes the name of the account(Account_Name). We can use the external field's value in the Accounts module, instead of the account name while inserting an event.
Base Module: Events
External field's API name in Accounts: External_Account_ID; Value: extAccount1
Header: X-EXTERNAL: Events.What_Id->Accounts.External_Account_ID
Request URL: https://www.zohoapis.com/crm/v3/Events
Input body:
{ "data": [ { "se_module": "Accounts", "What_Id": { "External_Account_ID": "externalaccount1" }, "Event_Title": "Event Kaizen", "Start_DateTime": "2023-01-01T10:10:10+05:30", "End_DateTime": "2023-01-01T11:10:10+05:30" } ] } |
You can also add participants(Leads or Contacts) to an event through their external IDs. Here is an example.
Header: X-EXTERNAL : Events.What_Id->Accounts.External_Account_ID,Events.Participants.participant->Contacts.External_Contact_ID
{ "data": [ { "Participants": [ { "type": "contact", "participant": { "External_Contact_ID": "extenalcontact3" } } ], "What_Id": { "External_Account_ID": "externalaccount1" }, "$se_module": "Accounts", "Event_Title": "Kaizen 1", "Start_DateTime": "2023-05-10T10:10:10+05:30", "End_DateTime": "2023-05-10T11:10:10+05:30" } ] } |
Note
You can use the same logic for updating records in Zoho CRM through external fields.
Upserting records using external values
Normally, in an upsert API call, the system checks for duplicates based on the system-defined duplicate check fields and user-defined duplicate check fields.
While upserting through external fields, the system considers the external field as a system-defined unique field, checks for the following:
- If the external value is unique and the other duplicate checks are done, the system inserts the record if no matching record is found.
- If the external value already exists in a record, the system updates the other fields given in the input to the matching record.
- If the external value does not exist, the system checks for the system-defined and user-defined duplicate check fields. If a match is found, the system updates the record with the new external value along with other fields in the input.
How upsert works for org-based and user-based external fields?
- Org-based external fields
Consider that a user inserts a record using the external value. Now, when another user tries to create a record with the same external value as the previous user's, the system throws the DUPLICATE_DATA error. - User-based external fields
Consider that a user creates a record with an external value. When the same user upserts using the same external value, the system updates the record.
Note that you need not pass the X-EXTERNAL header for upsert operation as the system considers external field to be unique, anyway, and performs duplicate check.
Deleting records using external fields
You can use the external field's value in the request URL and in the "ids" parameter, instead of CRM's record ID.
Here are the sample requests:
Header: X-EXTERNAL: Contacts.External_Contact_ID
Header: X-EXTERNAL: Contacts.External_Contact_ID
Searching for records in a module using external values
You can use the external field's API name and its value in the "criteria" parameter of the search Records API.
The supported operators are "equals" and "in".
Here are the sample requests:
Header: X-EXTERNAL: Contacts.External_Contact_ID
- https://www.zohoapis.com/crm/v3/Contacts/search?criteria=(External_Contact_ID:in:usercontact2,usercontact123)&fields=External_Contact_ID,Email
Header: X-EXTERNAL: Contacts.External_Contact_ID
- https://www.zohoapis.com/crm/v3/Contacts/search?criteria=(External_Contact_ID:equals:usercontact2)&fields=External_Contact_ID,Email
We hope you found this post useful. Let us know your questions in the comment section or write to us at support@zohocrm.com.
Cheers!
Shylaja
Shylaja
Previous Kaizen Post: Kaizen #63 - Layout Rules in Zoho CRM
Access your files securely from anywhere
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Shylaja S
Sticky Posts
Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! CommandsKaizen #165 : How to call Zoho CRM APIs using Client Script
Welcome back to another exciting Client Script post! In this post, we will discuss one of the most frequently asked questions: How do you call Zoho CRM APIs from Client Scripts? In this kaizen post, 1. Ways to make calls to Zoho CRM APIs using ClientKaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provideExtension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use APIKaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
New to Zoho TeamInbox?
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
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Ticket Response Email Template
Is there a way to have an email template automatically selected when I click on Reply for a ticket?Unpublishing Job Post for LinkedIn
Hi, We have experienced issue with the above. We did unpublish a job in Recruit but it still appear under Job section in our LinkedIn page. It did not remove from LinkedIn as it should be. Please check and advise. Regards, SnyderPower of Automation :: Automatically start / pause / stop timer on task status update.
Hello Everyone, A Custom function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:-Editor limitations to define screen types
Guys I have noticed that even in version 2.0 of the editor (which is this new one we use) we still have a lot to improve... When I compare to some more global solutions like Wix, Zyro, Go Daddy, Squarespace and Weebly feel that we have some limitationsDúvidas do Zoho Creator
Pessoal, Estou colocando um tópico para dúvidas do Zoho Creator. Um abraço, LeandroTropicalize Books
Books is an incredibly powerful tool that works well in many countries. But I feel that it is a product that is not yet "tropicalized" for Brazil as we speak (this would be like adapting the local reality). We have many strong competitors who do moreAutomatic Sitemap Generation
Guys are all right? Doesn't make sense for me to have to generate a map site and upload it... because it's not automatically generated just as it is done in WIX? where the customer doesn’t have to worry about this.SEO improvements with ZIA
Are you okay? I would like to bring an idea that would be amazing to improve the product that is the possibility of being able to improve the SEO of the pages (this of each page or each article on the blog) through ZIA so that it could create page SummaryAutomatically updating field(s) of lookup module
I have a lookup field, which also pulls through the Status field from the linked record. When the lookup is first done, the Status is pulled through - this works perfectly. If that Status is later updated, the lookup field does not update as well. AsInitiating a SalesIQ Zobot from a custom button on Zoho Sites
I have created a Zobot set to initiate on a custom action called "Fast_Answers". On Zoho Sites, I created a code snippet button and set it to on-click run the event called "Fast_Answers". I installed the SalesIQ integration code into the Zoho Sites PageZoho Desk -> Zoho Analytics : Where is the field for "Layout" ?
I have many different layouts on my helpdesks and I want to be able to identify the stats for each one, however I can not file the field in the raw data from the Zoho Desk datasource. I thought it might be under "Tickets" but there is nothing. There isSet resolution mandatory field
Hi, i have 2 questions:) : - i want to set the resolution field mandatory before close the ticket. Because for now, i can close the ticket without writing how i solve it - how can i setup zoho desk to receive ticket by email(e.g. clients sent email to support@mydomain.com) and it create a ticket in zoho deskImpuesto automatico en cotizaciones
Buen dia Mi pregunta es como se puede poner alguna operacion para que las cotizaciones me salgan automaticamente con impuestos ya que uno al cargarla al final tienen que añadir el porcentaje de impuesto SaludosZoho Assist "Agree and Download" Button "Greyed Out" ("Light Blued" Out)
Anyone else having issue where support clients are unable to click "Agree and Download" to access the client so that we can provide remote support? This is for "on demand" support via accessing the support page and entering the support key and name. ThisProject Billing with the Staff Hours Method in Zoho Projects
The Staff Hours Billing Method in Zoho Projects allows you to bill your clients based on the actual time spent by each team member on a project, at the rate set for each user. This is useful for projects where different skill sets are needed and serviceCreator Subform to CRM Subform
Hello all, Has anyone successfully written data from a Creator Subform into CRM subform? I have been able to get the rows to populate but none of the data will come through. I'll add my code and the result in CRM. Creator Subform is 'Delivery_Receiving_Hours'.custom fields not populating from deluge script into invoice
Hello, I've created some Deluge script that is meant to take a few inputted invoice custom fields and calculate a few others. I can see when I execute the function that my inputted custom fields are being passed, yet im still ending up with all "null"tax summation function - getting error
Hello, I'm trying to create a function that adds all of individual tax rates from a few jurisdictions. I'm getting an error on line 9 - Value is empty and 'get' function cannot be applied. I've checked that I have data in each of the required fields,Backstage / Zoho Books integration
Hello. We have Zoho One and have slowly started using Backstage. Loving it. Problem is, we have ZERO accounting control over what is sold through this product. When will we be able to connect it to our existing Zoho Books tenant? Thank you very much!Getting list of calendar events over api for zoho mail calendar
Hi, I am using just Zoho mail without using Zoho CRM. I wanted to get all events booked in my zoho mail calendar through an api at regular intervals. I could find such API support for Zoho CRM calendar but not for zoho mail calendar. Can you kindly letAllocate emails to user in a shared mailbox
Hi, This might be obvious, but I cannot find the answer. I have 3 shared mailboxes so any team member can see the emails. Is there a way of allocating a specific email to a user so that it is their responsibility to deal with it? Thanks in advance.Introducing Zoho Campaigns' own gateway for SMS campaigns
We are excited to announce the launch of our SMS Gateway to send SMS through Zoho Campaigns. We have also made a few other changes in our current SMS Campaign model to improve your over all user experience. These updates are planned with an aim to expandUpdate a lookup field in CRM from Creator using deluge
I have a Creator form that creates a new account. When it creates the new account in the Accounts Module, I need it to also populate the Parent Account, which is a lookup field coming from the Module Parent Accounts, field Parent Account Name. I haveSMS Keyword Tracking in Zoho CRM From Zoho Campaigns
Is there a way to track SMS leads in campaigns by associating them with specific keywords or codes? Additionally, can these leads be pushed to the CRM while retaining the keyword for tracking and reporting purposes?Projects Multiselect API
Having troubles setting a mutli select field via API. updateMap = map(); updateMap.put("UDF_MULTI1","picklist_id1,picklist_id2"); updateProjectRes = invokeurl [ url :"https://projects.zoho.com/restapi/portal/XXXX/projects/" + projectID + "/" type :POSTBill quantity received / PO quantity
PO's are raised & often the quantity received is greater than the PO quantity, so when we receive the bill & adjust the quantity on the bill we get.... Quantity recorded cannot be more than quantity ordered. This necessitates the adjustment of the POZOHO BOOKS - RECEIVING MORE ITEMS THAN ORDERED
Hello, When trying to enter a vendor's bill that contains items with bigger quantity than ordered in the PO (it happens quite often) - The system would not let us save the bill and show this error: "Quantity recorded cannot be more than quantity ordered."Adding Bluesky channel
Hello, Is Bluesky (AT protocol) soon added on Social ? Bluesky is being developped and is now open to anyone (no more invitation) Thank youUsing Queries with dynamic parameters in Kiosk Studio
Hi, I'm pretty new when it comes to developing within Zoho (I'm really a .NET developer), as it was just added to my responsibilities. For a new feature in the CRM, I'm trying to develop a Kiosk function to show a list of records (retrieved by the newUnused items should not count into the available number of custom fields
Hey, I realized that unused Items reduce the number of available custom fields. I can't see a case where that makes sense. Especially in our case where we have two different layouts in Deals with a lot of different fields, this causes problems.Introducing Bot Filtering for Accurate Email Campaign Analytics
Dear Marketers, We're excited to announce a new feature designed to enhance the accuracy of your email campaign analytics: bot filtering. This feature helps you filter out bot-generated opens and clicks, ensuring your campaign reports reflect genuineTip 37: Time Log Restriction in Zoho Projects
Timesheet in Zoho Projects helps you big time in entering log hours for the tasks and issues and approving them. Now, with the new Time Log Restriction option, you can set daily and weekly log hour limits. You can restrict users from entering extra log hours than the permissible limit. The limits are restricted to 24 hours per day and 168 hours per week by default based on business hours. To customize, navigate to Task & Timesheet settings under Portal Configuration in Zoho Projects setup and enableChart showing schedule
I want to be able to create a chart for everyday to check and which of which driver is available on the timeframe. Here's my table Name City Day Start Time End Time Driver1 Medicine Hat Monday 11:45 AM 4:45 PM Driver 2 Medicine Hat Tuesday 11:00 AM 7:00Multiple Vendor SKUs
One of the big concerns we have with ZOHO Inventory is lack of Vendor Skus like many other inventory software packages offer. Being able to have multiple vendor skus for the same product would be HUGE! It would populate the appropriate vendor Sku forIn Zoho Projects, is there a way to create a folders template under documents that can be used once a project is created?
We have a specific folder structure that we would like to use that is standard across every project. Instead of having to create this structure every time a project is created, is there a way to create a template for the folders that can be added?Zoho Payroll in France
When will Zoho Payroll be available in France ?Blueprint - 'On hold' state with an automatic transition?
I think I'm missing something here so I'm hoping if I explain what I'm trying to achieve someone might be able to give me a way around it. We sometimes get request far in advance but we don't want to action them unless it is 7 days from when they areHOW TO VIEW INDIVIDUAL COST OF NEWLY PURCHASED GOODS AFTER ALLOCATING LANDED COSTS
Hello, I have been able to allocate landed costs to the purchase cost of the new products. however, what i need to see now is the actual cost price (original cost plus landed cost), of only my newly purchased products to enable me set a selling priceClient Script: $Client.refresh({ triggerOnLoad: true }); not triggering onLoad Client Scripts
Hey friends! I'm trying to store a temporary var, refresh the page for the user, then check that temporary var and do some actions. Theoretically using the title's code: $Client.refresh({ triggerOnLoad: true }); should refresh the page and trigger onCalculate months and years between 2 dates on subform
I am looking for a function syntax for an employment candidate to calculate the number of years and months (decimal format. eg 1.2 years) they are employed. I have their start date entered, but if the end date is blank, that tells me they are still employedNext Page