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
New to Zoho Recruit?
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
Kaizen #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Kaizen #198: Using Client Script for Custom Validation in Blueprint
Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Celebrating 200 posts of Kaizen! Share your ideas for the milestone post
Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQsKaizen #193: Creating different fields in Zoho CRM through API
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.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! Commands
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator 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
Zoho Devops
We have a Zoho one account which we have integrated with an SAS educational product, sold on a subscription model, using webhooks and API calls. We make some use of custom fields and cross module lookups and relationships. We utilize CRM, Books and billingFuel up your sales with the Zoho SalesIQ + Bigin integration
Hi everyone! We’re happy to bring you the all-new Zoho SalesIQ + Bigin integration. With this, every prospect from your website instantly becomes a contact in Bigin, complete with transcripts and follow-up tasks, so you never lose a lead again. Let'sAdd a 'Log a Call' link to three dot icon in Canvas
Hi, There's a three dot element when creating a canvas called 'More'. I would like to modify this to add a link that says 'Log a Call' in order to quickly record the details of a cellphone call. I'd also like this to be a simple 'contact' selection andIntroducing AI-powered Assessments & Zoho's native LLM, Zia
We’ve shipped a cleaner, faster way to create assessments in Zoho Recruit. 🚀 Instead of manually building question banks or copying old templates, you can now generate ready-to-use assessments in just a few clicks, all tailored to the role you’re hiringAbility to Reset Visitor Fields During an Active Chat Flow
Hello Zoho SalesIQ Team, We hope you are doing well. We would like to propose a feature enhancement to Zoho SalesIQ regarding the management of visitor fields within Zobot flows. Use Case: Our bot asks the visitor to provide information about a 3rd personExternal ID in Zoho CRM
Hello everyone! We know that Zoho CRM allows you to integrate third-party apps and manipulate data through APIs. While you integrate a third-party application, you may want to store the third-party reference IDs in Zoho CRM's records. To meet this needSome emails are not being delivered
I have this problem where some of my mail just seems to disappear. When I send it, it appears as sent with no mention of any problem, but my recipient never gets it, not even in the Spam folder. Same for receiving, I have a secondary e-mail address, andNew in Zoho Chat : Search for contacts, files, links & conversations with the all new powerful 'Smart Search' bar.
With the newly revamped 'Smart Search' bar in Zoho Chat, we have made your search for contacts, chats, files and links super quick and easy using Search Quantifiers. Search for a contact or specific conversations using quantifiers, such as, from: @user_name - to find chats or channel conversations received from a specific user. to: @user_name - to find chats or channel conversations sent to a specific user. in: #channel_name - to find a particular instance in a channel. in: #chat_name - to findTemplate modifiactions
Hello, I am struggling with the templates in ZOHO Books. Especially with the placement of some items, like company address, ship to, bill to etc. For example: One item I like from template X (placement of ship to and bill to next to each other in theAggregating the First Value in the Group By of a dataset
Hi I am trying to get the following Aggregate Formula to work in my chart, but cannot seem to get the right format. I have a series of data that I am running an include_groupby and want to SUM only a column in the first row of each group. So for example.Admin Control Over Profile Picture Visibility in Zoho One
Hello Zoho Team, We hope you are doing well. Currently, as per Zoho’s design, each user can manage the visibility of their profile picture from their own Zoho Accounts page: accounts.zoho.com → Personal Information → Profile Picture → Profile PictureTrack Zoho Campaign and Workflow sales impact
I am attempting to measure the performance of our marketing workflows and campaigns by comparing the date each campaign was sent to a contact with the purchase date of the contact. For example, if Contact A was sent Email A on 9/1 and made a purchaseTables for Europe Datacenter customers?
It's been over a year now for the launch of Zoho Tables - and still not available für EU DC customers. When will it be available?What is a line break code for zoho?
Hi, I am archiving data by adding values from a single line field from one form to a multi-line field in another form. So I need a code/function that starts a new line on that multi-line field so it does not just keep adding it on the same line. Example, doing something like this means that it will be on a same line. archive.field1 = archive.field1 + input.Field1 I need a code so the input.Field1 can just start on the next line. Instead of "value 1, 2,3,4,5" It will be: "1 2 3 4 etc.". somethingAutomatic Project Owner change
Is there a way to change Project Owner automatically once a specific Milestone in a project is marked as completed. Different Teams are working on projects in our Org, they have their own Milestones to complete and so we transfer the project from teamButton to add product to cart
Is there a way to have a button on a page, that when clicked, will add Qty 1 of a product to the cart?Problem with Submit Button Design
I have made a template to apply to my forms and under the button controls, I have it set to "standard" and yet it's still filling the container. This is super frustrating and looks weird. Why do we not have full control over button size? How can I fixZoho CRM- Authorize your Microsoft Teams account issue
Hi, I tried to link Zoho CRM with Teams and I got the following message: Clicking "Authorize now" sent me to the following page, Microsoft tried to start a session but, after 3 seconds the page closed and nothing happened. I get the same message eachPassing the CRM
Hi, I am hoping someone can help. I have a zoho form that has a CRM lookup field. I was hoping to send this to my publicly to clients via a text message and the form then attaches the signed form back to the custom module. This work absolutely fine whenIs there a way to associate an email in ZOHO Main to a Vendor record in ZOHO CRM
My situation is as below, I have a vendor in ZOHO CRM lets say "Vend A" and an associated contact, "Cont A" If Cont A sends me an email using the email I've registered in the contact record the standard OOTB email sync will work. But the vendor has someBank charges are applied. Please select a bank account.
Hello, I'm trying to add bank charges to a customer payment, but I get the error message "Bank charges are applied. Please select a bank account." I found this old thread, where it says that I need to "select a Bank account for the 'Deposit To' dropdownKaizen #207 - Answering your Questions | Advanced Queries using COQL API
Hi everyone, and welcome to another Kaizen week! As part of Kaizen #200 milestone, many of you shared topics you would like us to cover, and we have been addressing them one by one over the past few weeks. Today, we are picking up one of those requestsPrésentation de SecureForms dans Zoho Vault
Soyons francs : demander à quelqu’un de transmettre un mot de passe ou des informations sensibles n’est jamais une tâche facile. On attend, on relance, parfois de nombreuses fois. Et quand l’information arrive, elle se retrouve souvent dispersée dansIntroducing Connected Records to bring business context to every aspect of your work in Zoho CRM for Everyone
Hello Everyone, We are excited to unveil phase one of a powerful enhancement to CRM for Everyone - Connected Records, available only in CRM's Nextgen UI. With CRM for Everyone, businesses can onboard all customer-facing teams onto the CRM platform toGranular Email Forwarding Controls in Zoho Mail (Admin Console and Zoho One)
Hello Zoho Mail Team, How are you? At present, the Zoho Mail Admin Console allows administrators to configure email forwarding for an entire mailbox, forwarding all incoming emails to another address. This is helpful for delegation or backup purposes,Sales order & purchase order item links for item details
This is fantastic for checking lots of things, I use it a lot. It would be great to see it extended to invoices & bills On another note, may as well throw in my favourite whinge ..... Wish you guys would get the PO receive differences sorted urgently,Custom Fonts in Zoho CRM Template Builder
Hi, I am currently creating a new template for our quotes using the Zoho CRM template builder. However, I noticed that there is no option to add custom fonts to the template builder. It would greatly enhance the flexibility and branding capabilities ifZoho Workdrive - Communication / Chat Bar
Hi Team, Please consider adding an option to allow admins to turn on or off the Zoho Communication Bar. Example of what I mean by Communication Bar: It's such a pain sometimes when I'm in WorkDrive and I want to share a link to a file with a colleagueIntroducing Profile Summary: Faster Candidate Insights with Zia
We’re excited to launch Profile Summary, a powerful new feature in Zoho Recruit that transforms how you review candidate profiles. What used to take minutes of resume scanning can now be assessed in seconds—thanks to Zia. A Quick Example Say you’re hiringKaizen #190 - Queries in Custom Related Lists
Hello everyone! Welcome back to another week of Kaizen! This week, we will discuss yet another interesting enhancement to Queries. As you all know, Queries allow you to dynamically retrieve data from CRM as well as third-party services directly withinNeed the ability to have read only fields on a form.
There needs to be functionality in Creator that allows a field on a form to be read only. Most screen building software applications have this capability. I know you can hide certain fields from specific users and that you can also make the whole form read only but that's not the functionality I need. I want to be able to create a form where certain fields are editable and other are for display purposes only (read only). For example if the form was displaying information on an item that the userReverse payment on accidentally closed invoice.
An invoice was closed accidentally with the full payment added. However, only partial payment was paid. How can I reopen the invoice and reverse this to update it to show partial payment?New integration: Track booking page appointments in Google Analytics 4
Hello all, Greetings from the Zoho Bookings team! We’re excited to introduce our new Google Analytics 4 (GA4) integration designed to help you track booking activity, understand customer behavior, and measure marketing performance, all in one place. WhatHow to list emails in a folder, e.g. Inbox, on multiple pages when using Zoho mail webpage?
Something as shown in the figure. There are totally 50 emails in Sent folder. If "Mail per page" equals 20, then the Sent folder is split into 3 pages. When I wander through Sent folder, I can just select a specific page to jump to. BTW, it seems thatHow to add image to items list in Invoice or Estimate?
Hello! I have just started using Zoho Invoice to create estimates and, possibly to switch from our current CRM/ERP Vendor to Zoho. I have a small company that is installing CCTV systems and Alarm systems. My question is, can I add images of my "items" to item list in Zoho Invoice and Estimates and their description? I would like to show my clients the image of items in our estimates so they can decide if they like these items. And I tell you, often they choose more expensive products just becauseZoho Calendar soft bounce on @hotmail.com and @yahoo.com email addresses
Hello, our Zoho calendar recently does not send the calendar invites to emails with hotmail and yahoo domains and comes back with a "soft bounce". other domains like Gmail works fine. Also sending "email" to the same emails to the above domains work wellHow can I filter a field integration?
Hi, I have a field integration from CRM "Products" in a form, and I have three product Categories in CRM. I only need to see Products of a category. Thanks for you answers.ERROR CODE :512 - 5.4.4 DNS error:NXDOMAIN.
Suddenly we cant send mail, we are getting this error for all outbound mail to multiple domains.Can Zoho Flows repeat Actions more than once?
I'm attempting to make an intentional Zoho Flow loop using the below layout. However, when "WithinLimit" condition is met, the program fails to execute the action "Get & Add Request Co..." again. Is this by design? Is Zoho Flows unable to repeat actionsUnveiling Cadences: Redefining CRM interactions with automated sequential follow-ups
Last modified on 01/04/2024: Cadences is now available for all Zoho CRM users in all data centres (DCs). Note that it was previously an early access feature, available only upon request, and was also known as Cadences Studio. As of April 1, 2024, it'sNext Page