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

                                                                                                            • Multi-currency - What's cooking ?

                                                                                                              Hi,       We have been doing this feature for sometime and we would like to give you some glimpses of it.  Working with Multi Currency :        Multicurrency support gives you the ability to handle business transactions in multiple currencies. You can define a base currency for your organization and add more currencies with exchange rates based on the base currency.  Setup :        From the setup page, you can manage all the currencies supported by your organization.       Currencies page        

                                                                                                            • Integrating Chatbot with Zoho Creator Application

                                                                                                              Is it possible to integrate a chatbot with a Zoho Creator application?

                                                                                                            • How to reduce programmatically the image uploaded by user?

                                                                                                              I need a function that will automatically reduce the pixel dimension to 800 x 600 pixels / 180 resolution or (approx. 1.37MB) of image uploaded by user from digital camera, for example, 2271 x 1704 pixels /180 resolution or approx. 11.1MB. After the user selected the image, the function will able to detect if pixels is above 800x600, process the photo (crop/ reduce) and resume upload. Need help...  

                                                                                                            • Dark mode for Zoho Creator / Zoho CRM Code editor

                                                                                                              Hi Team, Is there any plans for Dark mode in Zoho creator / Zoho Crm code editor and development pages in pipeline?

                                                                                                            • Is there a way to make a button scroll down?

                                                                                                              Looking to have a button on a landing page scroll down to another section on the page. Any recomendations outside of coding?

                                                                                                            • Collective-booking event not added to all staff calendars

                                                                                                              We assign two staff to certain events. When the client books this event, it adds it to one staff calendar (the 'organiser') but not the other. How can I ensure all staff assigned to a collective booking get the event in their calendar? (A side note: it

                                                                                                            • ZOHO Android Client

                                                                                                              Hi, I installed the Android app, but it had an issue, so I reinstalled it. I was able to add multiple accounts, but now when I add the next account, it just duplicates the one I already have and will not even allow me to enter the info for another account.

                                                                                                            • I'd like to suggest a feature enhancement for SalesIQ that would greatly improve the user experience across different channels.

                                                                                                              Hello Zoho Team, Current Limitation: When I enable the pre-chat form under Brands > Flow Controls to collect the visitor’s name and email, it gets applied globally across all channels, including WhatsApp, Messenger, and Instagram. This doesn't quite align

                                                                                                            • Enhance Barcode/QR Code scanner with bulk scanning or continuously scanning

                                                                                                              Dear Zoho Creator, As we all know, after each scan, the scanning frame closes. Imagine having 100 items; we would need to tap 100 times and wait roughly 1 second each time for the scanning frame to reopen on mobile web. It's not just about wasting time;

                                                                                                            • Managing Rental Sales in Zoho Inventory

                                                                                                              I am aware that Zoho Inventory is not yet set up to handle rental sales and invoicing. Is anyone using it for rentals anyway? I'd like to hear about how others have found work arounds to manage inventory of rental equipment, rental payments, etc. Th

                                                                                                            • Megamenu

                                                                                                              Finally! Megamenu's are now available in Zoho-Sites, after waiting for it and requesting it for years! BUT ... why am I asked to upgrade in order to use a megamenu? First: Zoho promised to always provide premium versions and options for all included Zoho-applications

                                                                                                            • Zoho Flow to Creator 3001 Respoonse

                                                                                                              I have updated my Flows with the new V2 connection to Zoho Creator, but now some Flows do not work. They take in data from a Webhook and are supposed to create a record in Creator, however creator returns a 3001 message along with a failure, but I cannot

                                                                                                            • File Upload to Work Drive While Adding Records in Zoho Creator Application

                                                                                                              Hi I am trying to set a file attachment field in zoho creator form, to enable the user to upload a scanned document from their local pc. The file should be uploaded to zoho workdrive and not to the default zoho creator storage. The file link should be

                                                                                                            • Why not possible to generate?

                                                                                                              Using this https://desk.zoho.com/DeskAPIDocument#TicketCount#TicketCount_Getticketcountbyfield on my ZML script url :"https://desk.zoho.com/api/v1/ticketsCountByFieldValues?departmentId=XXXXXXXXXXX&accountId!=XXXXXXXXX&customField1=cf_country_1:XXXXXX&field=overDue"

                                                                                                            • email

                                                                                                              Hi My crm email is not working, can you check, I have zoho one account.

                                                                                                            • Need option to see Mass Emails & Cadences in Gmail Outbox OR a dedicated Zoho Outbox

                                                                                                              Hi everyone, Right now, when we send 1:1 emails from gmail (with gmail API connected to Zoho CRM), those emails appear both in gmail's sent folder and in Zoho CRM. That works well. But when we send Mass Emails or Cadence emails form Zoho CRM, they are

                                                                                                            • I can't found API for Sales Receipts

                                                                                                              Hello May you please help me to find an API document for Sales Receipts to get data and retrive a custom fields like Invoice and credit notes Regards

                                                                                                            • Kaizen #205 - Answering Your Questions | Managing Picklists and Enabling History Tracking via Zoho CRM APIs

                                                                                                              Hello everyone! Welcome back to another post in our Kaizen series. In this post, we will look at how you can manage picklist fields in Zoho CRM using APIs. This topic was raised as feedback to Kaizen #200, so we are taking it up here with more details.

                                                                                                            • Multiple 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 for

                                                                                                            • Internally created tickets

                                                                                                              Hi there When tickets are created internally on-behalf of customers - there is nothing to show that the ticket was created by an internal agent. This means, that it's easy for our agents to confuse tickets which were created by internal team members and

                                                                                                            • Automatically change website passwords

                                                                                                              Hi everyone, We just switched to a Professional package to also use the "Automatically change website passwords" function. But I cannot find anything about it, how to use it, anywhere. Does anyone know how I can use this function? Best, Caspar

                                                                                                            • Change Invoice Prices for an Effective Date

                                                                                                              Hi, It would be a really good feature to be able to change the prices on invoices/recurring invoices from an effective date in the event of price increases. For instance, I am in the process of increasing prices that will be effective from a specific

                                                                                                            • "Other Current Asset" accounts as "Paid Through" accounts in Expense

                                                                                                              It would be incredibly useful to be able to assign accounts of type Other Current Asset as Paid Through accounts in Expense. Currently, Other Current Liability are permitted as Paid Through Accounts. This makes sense, as Credit Cards are current liabilities.

                                                                                                            • Multi column open text questions that allows respondents to add rows for additional information

                                                                                                              I need to create a question that has 2 columns with open text, but I also need to allow respondents to click a "+" button, or something similar, so that they can add additional information if they choose to. I've tried using the Multiple Textboxes type

                                                                                                            • Bot Filtering & Apple Mail Privacy Protection Compliance in Zoho Campaigns

                                                                                                              Dear Campaigns Users, The wait is over! We’re excited to announce that the enhanced bot filtering feature is now live in Zoho Campaigns. This update brings greater accuracy to your email campaign reports by distinguishing real user engagement from automated

                                                                                                            • Découvrons les détails qui simplifient vos journées de travail avec Trident

                                                                                                              Nous nous installons dans des routines efficaces et rodées avec le temps. Chaque matin, nous ouvrons nos e-mails, passons aux messages, consultons notre agenda, puis attaquons nos tâches. Ce processus nous semble maîtrisé, mais est-il réellement optimisé

                                                                                                            • Issue with Purchase Rate Showing as “0” After Importing Items List

                                                                                                              Dear Zoho Books Support Team, Good day. I’m reaching out regarding an issue I’m facing while importing my items list into Zoho Books. Despite mapping all fields correctly and including the purchase price for each product in my Excel file, the Purchase

                                                                                                            • API for Task Entity in Zoho Books

                                                                                                              I’m working on automating task creation in Zoho Books via a custom button in the Bills Module. The goal is to create a task in the Tasks Module and assign it to the Finance Team, so they can track progress efficiently. While reviewing Zoho Books documentation,

                                                                                                            • create invoice in zoho books from the zoho forms

                                                                                                              Is there a native way to have create invoice in zoho books, when zoho form is completed?

                                                                                                            • Email undelivered

                                                                                                              GOod Day I am always receiving an uncategorized-bounce to my email. I am not sure why this is happening.

                                                                                                            • Add inventory_valuation_method to items endpooints

                                                                                                              To ensure consistent item creation it would be helpful to have the inventory_valuation_method (FIFO vs WAC) be able to be set at item creation or as an update (consistent with current behavior where it is not allowed for items with existing transactions)

                                                                                                            • Use Zoho to send sales receipts for Gocardless transactions

                                                                                                              I've been using gocardless for years and have d/d mandates set up on there. Each week we get bulk payments from customer d/d's. However, we need to send sales receipts to these customers. So I know I can sync mandates into Zoho, and then I can set up

                                                                                                            • Zoho - Gocardless sales receipts

                                                                                                              I've been using gocardless for years and have d/d mandates set up on there. Each week we get bulk payments from customer d/d's. However, we need to send sales receipts to these customers. So I know I can sync mandates into Zoho, and then I can set up

                                                                                                            • Introducing Rollup summary in Zoho CRM

                                                                                                              ------------------------------------------Moderated on 5th July'23---------------------------------------------- Rollup summary is now available for all organizations in all the DCs. Hello All, We hope you're well! We're here with an exciting update that

                                                                                                            • Introducing Connected Workflows in Zoho CRM for Everyone : Free Your Teams to Focus on What Matters

                                                                                                              Hello Everyone, We’re thrilled to introduce the next big evolution in Zoho CRM for Everyone -- Connected Workflows. This new feature builds on our commitment to deliver a CRM that’s truly inclusive, adaptable, and designed for consistent collaboration

                                                                                                            • Cooling-off Period Just Got Better: More Coverage, More Control

                                                                                                              We’ve enhanced the Cooling-off Period feature in Zoho Recruit to give you more control over repeat applications and referrals. This helps you maintain a cleaner, more efficient recruitment pipeline. With this enhancement, you can: Prevent duplicate candidate

                                                                                                            • Revenue Management: #7 Revenue Recongition in Construction & Real Estate Industry

                                                                                                              If you are in the construction or real estate business, you are used to long project timelines and progressive invoicing to keep up with your billing. But when does revenue get recognized? Will it happen when the contract gets signed? At different milestones

                                                                                                            • TikTok (and other social platform) Messages and comments of the past

                                                                                                              When I link a social channel, Zoho will show in "Inbox", "Messages" and "Contact" sections the interaction done in the past? (comment, messages...)

                                                                                                            • Restrict Employee mail deletion

                                                                                                              Dear Zoho, Is there a way where i can restrict my employees to delete any mails from their account

                                                                                                            • 554 5.1.8 Email Outgoing Blocked.

                                                                                                              Hi guys, I just singed up for mateusz.nowicki@zoho.com mail and I can't send any mails.. Why? Everytime I try to send something I got error like the one in the screenshot. Please, help me.

                                                                                                            • Next Page