Kaizen #64 - External Fields and Records APIs

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

  1. 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.
  2. 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?

  1. Go to Setup > Customization > Modules and Fields > Choose a module.
  2. Create a single line field and provide a name.
  3. Click the more options icon and select Edit Properties.
  4. In the Single Line Properties pop up, specify the field label, and check the Set External Field box.
  5. Choose the field's visibility and the type of the external field.


  6. 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
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 
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
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

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
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
  1. https://www.zohoapis.com/crm/v3/Contacts?ids=extcontact3,extcontact4

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
  1. 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
  1. 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


    Access your files securely from anywhere






                      Zoho Campaigns Resources


                            Zoho Developer Community



                                Bootcamp
                                Community
                                Pricing
                                Webinars
                                What's New
                                Integrations
                                Contact Support
                                Contact Sales

                                  Zoho Survey Resources
                                    Features
                                    Survey Templates
                                    Integrations
                                    Community
                                    iOS Mobile Surveys
                                    Pricing
                                    Android Mobile Surveys
                                    Insurvey Blogs
                                    Insight Blogs
                                    Tips & Tricks





                                                Latest Feature Updates
                                                  What's New in Zoho Desk

                                                  Use cases

                                                  Make the most of Zoho Desk with the use cases.

                                                   
                                                    

                                                  eBooks

                                                  Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho Desk.

                                                   
                                                    

                                                  Videos

                                                  Watch comprehensive videos on features and other important topics that will help you master Zoho Desk.

                                                   
                                                    

                                                  Webinar

                                                  Sign up for our webinars and learn the Zoho Desk basics, from customization to automation and more

                                                   
                                                    
                                                  What's New in Zoho Desk

                                                  • Desk Community Learning Series


                                                  • Meetups


                                                  • Ask the Experts


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner





                                                      Zoho SalesIQ Resources

                                                            • 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 FAQs

                                                            • Kaizen #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


                                                            Manage your brands on social media
                                                            Access Zoho Social

                                                              Zoho Pagesense Resources


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


                                                                                            Zoho Show Resources


                                                                                              Zoho Writer Writer

                                                                                              Get Started. Write Away!

                                                                                              Writer is a powerful online word processor, designed for collaborative work.

                                                                                                Zoho CRM コンテンツ








                                                                                                  Nederlandse Hulpbronnen


                                                                                                      ご検討中の方




                                                                                                            • Recent Topics

                                                                                                            • Invalid value passed for file_name

                                                                                                              System generated file name does not send file anymore - what is the problem?

                                                                                                            • Custom Function for Estimates

                                                                                                              Hey everyone, I was wondering if there was a way to automate the Subject of an estimate whenever one is created or edited: * the green box using following infos: * Customer Name and Estimate Date. My Goal is to change the Subject to have this format "<MyFirm>-Estimate

                                                                                                            • This domain is not allowed to add. Please contact support-as@zohocorp.com for further details

                                                                                                              I am trying to setup the free version of Zoho Mail. When I tried to add my domain, theselfreunion.com I got the error message that is the subject of this Topic. I've read your other community forum topics, and this is NOT a free domain. So what is the

                                                                                                            • Search in module lists has detiorated

                                                                                                              Every module has a problem with the search function :-/

                                                                                                            • YouTube Live #1: AI-powered agreement management with Zia and Zoho Sign

                                                                                                              Hi there! We're excited to announce Zoho Sign’s first YouTube live series, where you can catch the latest updates and interact with our Zoho Sign experts, pose questions, and discover lesser-known features. We're starting off by riding the AI wave in

                                                                                                            • Search in module lists has detiorated

                                                                                                              Every module has a problem with the search function :-/

                                                                                                            • Sales Receipts Duplicating when I run reports why and how do we rectify this and any other report if this happens

                                                                                                              find attached extract of my report

                                                                                                            • Add Zoho Forms to Zoho CRM Plus bundle

                                                                                                              Great Zoho apps like CRM and Desk have very limited form builders when it comes to form and field rules, design, integration and deployment options. Many of my clients who use Zoho CRM Plus often hit limitations with the built in forms in CRM or Desk and are then disappointed to hear that they have to additionally pay for Zoho Forms to get all these great forms functionalities. Please consider adding Zoho Forms in the Zoho CRM Plus bundle. Best regards, Mladen Svraka Zoho Certified Consultant and

                                                                                                            • Bigin: filter Contacts by Company fields

                                                                                                              Hello, I was wondering if there's a way to filter the contacts based on a field belonging to their company. I.e.: - filter contacts by Company Annual Revenue field - filter contacts by Company Employee No. field In case this is not possibile, what workaround

                                                                                                            • Has Zoho changed the way it searches Items?

                                                                                                              Right now all of our searches have broken and we can no longer search using the SKU or alias. It was fine last night and we came in this morning to broken.....this is impacting our operations now.

                                                                                                            • Refunds do not export from Shopify, Amazon and Esty to Zoho. And then do not go from Zoho inventory to Quickbooks.

                                                                                                              I have a huge hole in my accounts from refunds and the lack of synchronisation between shopify , Amazon and Etsy to Zoho ( i.e when I process a refund on shopify/ Amazon or Etsy it does not come through to Zoho) and then if I process a manual credit note/

                                                                                                            • CRM->INVENTORY, sync products as composite items

                                                                                                              We have a product team working in the CRM, as it’s more convenient than using Books or Inventory—especially with features like Blueprints being available. Once a product reaches a certain stage, it needs to become visible in Inventory. To achieve this,

                                                                                                            • Zoho Calendar not working since a few days

                                                                                                              Hey there, first off a minor thing, since I just tried to enable the Calendar after reading this in another topic (there was no setting for this though) : For some reason my current session is showing me based in New York - I'm in Germany, not using a

                                                                                                            • Monthly timesheet, consolidation of time by project

                                                                                                              I have time logs for various jobs for project. Is it possible to consolidate the time spent for each job, when I am generating a timesheet for a month? I am getting the entries of jobs done on each day when I generate a timesheet for a month For example

                                                                                                            • Building a Strong Online Identity with G-Tech Solutions

                                                                                                              In today’s fast-moving world, having a strong online identity is essential for every business. https://gtechsol.com.au helps businesses establish a digital presence that reflects their vision and values. By focusing on innovation and quality, they create

                                                                                                            • Sending emails from an outlook account

                                                                                                              Hi, I need to know if it's possible to send automatic emails from an Outlook account configured in Zoho CRM and, if so, how I can accomplish that. To give you some context, I set up a domain and created a function that generates PDF files to be sent later

                                                                                                            • Struggling with stock management in Zoho CRM – is Zoho Inventory the solution?

                                                                                                              My biggest pain point today with Zoho is inventory management. I run a retail business and reliable stock management is absolutely critical. Obviously, I need this inventory to be visible inside the CRM. At first, I tried handling it through custom modules

                                                                                                            • Automating CRM backup storage?

                                                                                                              Hi there, We've recently set up automatic backups for our Zoho CRM account. We were hoping that the backup functionality would not require any manual work on our end, but it seems that we are always required to download the backups ourselves, store them,

                                                                                                            • Nimble enhancements to WhatsApp for Business integration in Zoho CRM: Enjoy context and clarity in business messaging

                                                                                                              Dear Customers, We hope you're well! WhatsApp for business is a renowned business messaging platform that takes your business closer to your customers; it gives your business the power of personalized outreach. Using the WhatsApp for Business integration

                                                                                                            • can't login Kiosk URGENT

                                                                                                              already try, can't login pls help to support. thanks.

                                                                                                            • 【Zoho CRM】CRM for Everyoneに関するアップデート：関連データ機能

                                                                                                              ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 今回は「Zoho CRM アップデート情報」の中から、CRM for Everyoneの新機能「関連データ機能」をご紹介します。 関連データ機能は、あるタブのデータを別のタブに柔軟に関連付け、異なるタブで管理されている情報を1か所にまとめて表示できます。 たとえば、組織タブとチームタブのデータを関連付けることで、必要な情報に効率よくアクセスでき、顧客理解を深めながら他チームとの連携もスムーズに行えます。 目次 1. 関連データの設定方法

                                                                                                            • Zoho Books

                                                                                                              How do I manually insert opening balance?

                                                                                                            • Profit / margins on Sales orders / Invoices / Estimates

                                                                                                              When we select an SKU or item name in any of these documents, much info such as invoice.line_items.rate is pulled from the item & filled into the document being worked on. If we had another lineItem DB field (hidden) auto filled at the same time: invoice.line_items.purchase_rate

                                                                                                            • Inventory to Xero Invocie Sync Issues

                                                                                                              Has anyone had an issue with Invoices not syncing to Xero. It seems to be an issue when there is VAT on a shipping cost, but I cannot be 100% as the error is vague: "Unable to export Invoice 'INV-000053' as the account mapped with some items does not

                                                                                                            • How to activate RFQ? What if a price list has ladder price for items?

                                                                                                              Where can I find the option to activate request for quotation? How does it work? If the item has ladder price, does it gets calculated depending on how many items are in the cart?

                                                                                                            • Mailk got blocked / Inquiry About Email Sending Limits and Upgrade Options

                                                                                                              Dear Zoho Support Team, My name is Kamr Elsayed I created this account to use for applying for vocational training in Germany. As part of this process, I send multiple emails to different companies. However, after sending only 8 emails today, I received

                                                                                                            • Can't join canal Developers Zoho User

                                                                                                              Hello, I received an invitation to join this channel, but I get an error when I try to join it, and I get the same error when I go to the Zoho Cliq interface > Search for a channel. Is this because I don't have a license linked to this email address?

                                                                                                            • Desk Email reply - set default font / use custom font

                                                                                                              Hello, in our e-mails, which we send to our customers, a certain font must be used (Corporate Design): Segoe UI https://en.wikipedia.org/wiki/Segoe#Segoe_UI How can this be included? How can this be set as the default font to ensure that this font is

                                                                                                            • PDF Templates - Checkbox Borders

                                                                                                              Is there a way to remove the border of a radio/checkbox on a PDF? I'd like to use the function of checkbox but if there's no easy way to remove the border (the PDF form already has a rectangle so it gets cluttered), then I'm forced to create a single

                                                                                                            • Zoho CRM's custom views are now deployable from sandboxes

                                                                                                              This feature is now available for users in the AU, JP, and CN DCs. New update: This feature is now available for users in CA and SA DCs. Hello everyone, We're excited to announce that you can now deploy custom views from sandboxes to your production environment

                                                                                                            • Generate a link for Zoho Sign we can copy and use in a separate email

                                                                                                              Please consider adding functionality that would all a user to copy a reminder link so that we can include it in a personalized email instead of sending a Zoho reminder. Or, allow us to customize the reminder email. Use Case: We have clients we need to

                                                                                                            • UK MTD reports concerning turnover and cerash accounting

                                                                                                              Hi I am a sole trader, and I have just started with Zoho Books in order to comply with the new HMRC requirements. I use 'cash basis' - which I understand to mean that income is when the cash comes in (not the invoice date) and expenses are when they are

                                                                                                            • Settings Icon No Longer in ZOHO Desk?

                                                                                                              In ZOHO desk, there has been a gear icon for settings. as of yesterday, it is no longer there. I showed up briefly this morning but is gone again. Anybody else experiecing this?

                                                                                                            • Introducing the all-new email parser!

                                                                                                              Greetings, We are pleased to introduce to you, a brand-new, upgraded version of the Zoho CRM Email Parser, which is packed with fresh features and has been completely redesigned to meet latest customers needs and their business requirements. On that note,

                                                                                                            • Tip #43 - Track, Review, and Analyze Your Assist Sessions with Reports-'Insider Insights'

                                                                                                              Did you know you can generate detailed reports for both remote support sessions and unattended access sessions in Zoho Assist? This makes it easy to monitor technician activity, measure efficiency, and review customer interactions. Let us now take a closer

                                                                                                            • Function #20: Custom calculation in item table of invoices

                                                                                                              When you create an invoice in Zoho Books, the 'Amount' of a line item is typically calculated as the product of the "Quantity" and the "Rate" of the item. For instance, if an item has a sales rate of $50 and a quantity of 5 is sold, then the amount would

                                                                                                            • Can we generate APK and IOS app?

                                                                                                              Dears, I want to know the availability to develop the app on zoho and after that .. generate the APK or IOS app  and after that I added them to play store or IOS store.. Is it possible to do this .. I want not to use zoho app or let my customers use it. thanks 

                                                                                                            • CBSA - GST CHARGES on imports

                                                                                                              Hi there, We have a questions about landed cost categorization. We received a shipment from overseas. CBSA invoiced us for the GST on the items. Now we entered the CBSA-GST as a separate bill and attached it as landed cost to the main invoice based on

                                                                                                            • Simplified Call Logging

                                                                                                              Our organization would like to start logging calls in our CRM; however, with 13 fields that can't be removed, our team is finding it extremely cumbersome. For our use case, we only need to record that a call happened theirfor would only need the following

                                                                                                            • Sub form doesn't as formula field

                                                                                                              Is it possible to get formula field in sub form in futures?

                                                                                                            • Next Page