Kaizen #109 Record Locking Configuration APIs in Zoho CRM

Kaizen #109 Record Locking Configuration APIs in Zoho CRM

Hello everyone!

Welcome to Kaizen! In this post, we will discuss Record Locking Configuration APIs in Zoho CRM.

What is Record Locking?

Record Locking refers to the restrictions that you can apply to records of a module to prevent further changes to the data. You can either lock records manually or set conditions to lock them automatically.
   You can add record locking configuration to a module through the module builder. Go to Setup > Customization > Modules and Fields > {Module} > Record Locking Configuration. Record Locking is supported for Leads, Accounts, Contacts, Deals, Tasks, Cases, Solutions, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices and Custom modules.
Record Locking Configuration in UI
These options are available in record locking configuration:
  • You can lock all profile records or give exception to some profiles.
  • You can lock the activities you choose. The Edit option is limited by default. You can also limit delete action, adding tags, changing owner, sending emails or using custom buttons. 
  • You can have the option of editing certain fields even when the record is locked.

Automatic record locking 

Automatic record locking refers to the locking of records based on certain conditions. For instance, consider that a deal with a seller is in the closed won stage, and you want to prevent further changes to the deal record. You can achieve this using the record locking feature.
You can configure record locking for deals module to automatically lock a record when it reaches the closed won stage. You can specify rules for locking records. There can be up to five rules per module.

Manual Record Locking

Manual record locking is the intentional locking of a record by a user.  To do this, the user's profile should have adequate permission. Profile permissions can be set in Setup > Users and Control > Security Control> Profiles > {Profile Name} > Module Permissions > Tools > Lock.

Record Locking Configuration APIs

Record locking configuration APIs allows you to set up the configuration needed to lock the records in modules manually or automatically via APIs. 
The fields in Record Locking Configuration APIs are:

Name
Date Type
Description
locked_for
String
Represents whether records are locked for all profiles or some profiles. Possible value : all_profiles_except_excluded_profile or all_profiles
lock_excluded_profiles
String
Represents the profiles that are restricted from locking when  locked_for value is all_profiles_except_excluded_profile
excluded_fields
JSON Array
Represents the fields that are excluded from record locking
feature_type
String
Represents feature type, its value is record_locking for this case
locking_rules
JSON Array
Represents the details of rules added to lock the records in the module automatically. This array includes the name, id and criteria of locking rules. The field lock_existing_records indicates whether the existing record must be locked or not.
restricted_actions
JSON Array
Specifies the actions that are restricted for locked records. Possible values: update, delete, tags, change_owner
lock_for_portal_users
Boolean
Indicates whether locked records are restricted for portal users.
restricted_communications
JSON Array
Specifies types of communication that are restricted for locked records. Possible value: send_mail
system_defined
Boolean
Indicates whether the record configurations are system defined.
lock_type
String
Represents the type of the record locking configuration - manual, automatic, both
restricted_custom_buttons
JSON Array
Represents the name and id of custom buttons that are restricted for locked records.

Add Record Locking Configuration API

Using this API, you can configure record locking for the supported modules. 

Request URL:
{api-domain}/crm/{version}/settings/record_locking_configurations?module={module_API_name}
HTTP Method: POST
Let us consider the case of locking a deal automatically when it is in the closed won stage. 
Request URL to configure record locking for deals module:
{api-domain}/crm/v5/settings/record_locking_configurations?module=Deals

The below request body locks the records from editing for all profiles when the Deal Stage is Closed Won (lockings_rules).  The key lock_existing_records specify whether the rule should be applied for existing records. The record is locked for all profiles (locked_for) and the only field that is excluded from locking is the description field (excluded_fields). The record will be locked for portal users (lock_for_portal_users). Edit action is restricted for the lock record (restricted_actions). 

Request body:
{
  "record_locking_configurations": [
    {
      "locked_for": "all_profiles",
      "excluded_fields": [
        {
          "api_name": "Description"
        }
      ],
      "feature_type": "record_locking",
      "locking_rules": [
        {
          "name": "Closed Won",
          "lock_existing_records": true,
          "criteria": {
            "comparator": "equal",
            "field": {
              "api_name": "Stage"
            },
            "value": "Closed Won"
          }
        }
      ],
      "restricted_actions": [
        "update"
      ],
      "lock_for_portal_users": true,
      "restricted_communications": null,
      "system_defined": false,
      "lock_type": "automatic",
      "restricted_custom_buttons": null,
      "lock_excluded_profiles": null
    }
  ]
}

From the response of this API you will get the id of the record locking configuration.

The criteria JSON object inside the locking_rules JSON array consists of the comparator, field and value of the fields that form the locking rule of the configuration. If you want to give multiple conditions in one locking rule, you can use group_operator and group keys. The possible values for group_operator are AND, OR. For example, consider that you want to add a locking rule for Closed Lost deals which includes deals with Stage Closed Lost and Closed - Lost to Competition. This can be achieved by giving the locking_rules as shown below:
.
.
"locking_rules": [
                {
                    "name": "Closed Lost",
                    "lock_existing_records": true,
                    "criteria": {
                        "group_operator": "OR",
                        "group": [
                            {
                                "comparator": "equal",
                                "field": {
                                    "api_name": "Stage"
                                },
                                "value": "Closed Lost"
                            },
                            {
                                "comparator": "equal",
                                "field": {
                                    "api_name": "Stage"
                                },
                                "value": "Closed-Lost to Competition"
                            }
                        ]
                    }
                }
]
.
.

Get Record Locking Configuration API

Use this API to retrieve the details of record locking configuration for a particular module.
Request URL:
{api-domain}/crm/{version}/settings/record_locking_configurations?module={module_API_name}
HTTP Method: GET
Request URL to  retrieve the record locking configuration for deals module:
{api-domain}/crm/v5/settings/record_locking_configurations?module=Deals
{
    "record_locking_configurations": [
        {
            "created_time": "2023-10-23T03:25:06-04:00",
            "locked_for": "all_profiles",
            "excluded_fields": [
                {
                    "api_name": "Description",
                    "id": "5843104000000002587"
                }
            ],
            "created_by": {
                "name": "Patricia Boyle",
                "id": "5843104000000424672"
            },
            "feature_type": "record_locking",
            "locking_rules": [
                {
                    "name": "Closed Won",
                    "id": "5843104000001068052",//Locking rule ID
                    "lock_existing_records": true,
                    "criteria": {
                        "comparator": "equal",
                        "field": {
                            "api_name": "Stage",
                            "id": "5843104000000002565"// ID of Stage in fields API
                        },
                        "value": "Closed Won"
                    }
                }
            ],
            "restricted_actions": [
                "update"
            ],
            "lock_for_portal_users": true,
            "modified_time": "2023-10-23T03:42:00-04:00",
            "restricted_communications": null,
            "system_defined": false,
            "modified_by": {
                "name": "John Smith",
                "id": "5843104000000424001"
            },
            "id": "5843104000001068044",
            "lock_type": "automatic",
            "restricted_custom_buttons": null,
            "lock_excluded_profiles": null
        }
    ]
}

Update Record Locking Configuration API

Consider that you want to edit the above record locking configuration in deals module. You want to enable manual locking and also add a new rule to lock deals in stage closed lost. This can be done using the Update Record Locking Configuration API. 
Request URL:
{api-domain}/crm/{version}/settings/record_locking_configurations?module={module_API_name}
OR 
{api-domain}/crm/{version}/settings/record_locking_configurations/{record_locking_config_id}?module={module_API_name}
HTTP Method: PUT
Note that you should mention the ID of the record locking configuration inside the request body if you are using the endpoint that does not have the ID. 
When you specify a valid locking rule ID (obtained from Get Record Locking Configuration API) in the input body, the corresponding locking rule will be updated. When ID is not mentioned it will be considered as a new rule. 
In addition to adding or modifying existing locking rules in a specific record locking configuration, you can also delete locking rules using Update Record Locking API. When "_delete" key with value true is given in the input body, the locking rule will be deleted.

Example for deleting a record locking rule using update record locking configuration API 
Request URL: {api-domain}/crm/v5/settings/record_locking_configurations?module=Deals
HTTP Method: PUT

{
    "record_locking_configurations": [
        {
            "locking_rules": [
                {
                    "id": 5843104000001068052,//ID of record locking rule
                    "_delete": true
                }
            ],
            "id": "5843104000001068044"//ID of the record locking configuration
        }
    ]
}

Delete Record Locking Configuration API

   You can use this API to delete Record Locking Configuration for a module. Please note that deleting the record locking configuration of a module unlocks all the locked records of that module.
Request URL:
{api-domain}/crm/{version}/settings/record_locking_configurations/{record_locking_config_id}?module={module_API_name}
HTTP Method:DELETE
Request URL to  delete the record locking configuration for deals module:
​ {api-domain}/crm/v5/settings/record_locking_configurations?module=Deals

We hope you found this post on the Record Locking Configuration APIs useful. In next week's Kaizen we will cover Record Locking APIs  that enable users to access locking details for locked records, to lock/unlock manually, and to edit the locked reason for manually locked records.
If you have any questions, write to us at support@zohocrm.com or let us know in the comment section.
For more such posts that are part of our Kaizen series, please refer to our Kaizen collection here.

Cheers!




    • Recent Topics

    • Hosted Payment Pages - how to update the address in zoho billing

      I"m playing around with the muti-page hosted payment pages which have places for customers to enter their addresses when paying. Why does this not update their address in Zoho Billing after payment? What can I do to make this happen?

    • Tracking training certification expirations

      Hi Zoho Community! I'm looking for some input on the best and most efficient ways to track training expirations in Zoho CRM. I have a very specific workflow that I am looking for - my company offers trainings, and the certification expires every 2 to

    • Kaizen #164 : Client Credentials

      Hello everyone, Welcome back to Kaizen. In this post, we will discuss Client Credentials Flow and when it can be used. What is Client Credentials Flow? According to RFC6749, the official specification for the OAuth 2.0 authorization framework, "The client

    • CRM Email Template Align Left Instead of Center

      Is there a way to make a basic template align to the left instead of center? I know I'm likely forced to the 600px wide with the basic templates but I would REALLY like to set the email to the left instead of center. The basic templates make all the emails

    • Client Script - "Click' Button on Purchase Order - Specify "To Contact" or "To Supplier"

      The send email button is unique on the purchase order in that is has an additional submenu to send email "To Contact" or "To Supplier" It appears that the "click" event in Client script doesn't work correctly, probably because the button click didn't

    • Add Client Credentials Flow to Python SDK

      The Zoho CRM API supports a client credentials flow to automatically generate ephemeral access tokens, and this can be done programatically. The Python SDK however requires you to provide a grant token, refresh token, or access token when initializing

    • Conditional display of fields in Zoho Books Custom modules based on another field

      We're currently working with a Custom Module in Zoho Books and have a question about improving data entry efficiency and user experience. Our module includes a "Client Type" dropdown field, which determines the type of information to be collected. Each

    • Background Image for page in Zoho Creator

      Is it possible to use an image as the background in a page in Zoho Creator? I see it is possible to use an image as the background within a panel, but about about the page itself?

    • Zoho IP address blocked by Microsoft

      Today I tried to send emails to Outlook email addresses and all of them failed. The log displays like this: Reporting-MTA: dns; mx.zohomail.jp Arrival-Date: Fri, 27 Jun 2025 12:52:30 +0800 Original-Recipient: rfc822; ######@outlook.com Final-Recipient:

    • Request to Enable Full DNS Management Access for My Domain

      Hello Zoho Support Team, I have purchased the domain "digimarts365.online" through Zoho, and I need to add A and CNAME records to connect it with my Shopify store. However, DNS Toolkit is not allowing me to edit or add any records. Kindly enable full

    • Backup flow, see change log / history

      Hello, I would like to know, how flows can be saved, copied and tracked. If I work on a Flow with multiple other colleagues we need to see the Changes made by others. Is there a history, changelog or something else? Also we need to backup/import flows

    • Problème de validation du domaine spelam.ma

      Bonjour équipe Zoho, J’ai l’honneur de vous contacter car je rencontre un problème technique au niveau de la validation de mon compte ou de mon domaine spelam.ma. En effet, j’ai déjà acheté le domaine, mais la validation ne semble pas être correctement

    • Critical:- Eneble TDS filing for 26Q from the zoho book

      We currently extract TDS data from Zoho Books and manually input it into a separate TDS software to generate the FUV file and file returns. Previously, while using Tally, we benefited from an integrated feature that seamlessly recorded transactions and

    • Add a way of clearing fields values in Flow actions

      It would be great if there was an option to set a field as Null when creating flows. I had an instance today where I just wanted to clear a long integer field in the CRM based on an action in Projects but I had to write a custom function. It would be

    • Writer loads as a blank page.

      Hi, I'm new to zoho but I liked the idea of an online wordprocessor that I can use from multiple computers. I signed up a few hours ago while at work where our computers use Linus Ubuntu and a Firefox browser and the Writer came up fine. Now I'm home and using my Windows machine with Norton Firewall and Firefox and the writer opens as a blank page. I've checked my security options in both Firefox & Norton and I have received all the cookies from Zoho. What gives?

    • Ensure Consistent Service Delivery with Comprehensive Job Sheets

      We are elated to announce that one of the most requested features is now live: Job Sheets. They are customizable, reusable forms that serve as a checklist for the services that technicians need to carry out and as a tool for data collection. While on

    • JOB Sheet can not send PDF as service rapports and more info needed other topic

      Goedendag, - Jullie hebben nu job sheet erin gedaan en dar is echt super goed, enkel kunnen we de werkbon ( JOB sheet) nu niet verzenden als PDF als een service rapport naar onze hoofdaannemer hoe we dat nu doen als bewijs van de levering van het werk

    • Publish a single Sheet stopped working

      I used to have a published sheet on my Zoho Spreadsheet and that stopped working. If I want to publish it again, I only get the message that says "Published externally", but that does nothing, and if I change tabs and come back, the sheet gives me the

    • Does Zoho Contracts support white-labeling?

      As the title says, do you provide us white-labeling solution?

    • Constantly getting error 429 "Too Many Requests" despite not sending many requests.

      I am currently working on developing an integration between our company's app and our zoho books setup using the api. When testing new functionality, I am very often having the calls fail with Error 429 'You have made too many requests continuously. Please

    • Not receiving emails

      I'm able to send emails, but I can't receive any. Please help

    • Capturing knowledge across many channels

      We actively use Cliq for client discussions, product management etc. Often there are great answers to questions or key announcements. We have no way to tag or capture them along the way. Pinning only gets us so far. For example, imagine a product channel

    • Prepayment of a sales order

      How does everyone handle this common (at least it is common for us!) situation? We require all our orders to be fully prepaid before shipment since we manufacture made to order, custom products. Since ZOHO does not allow a sales order to be prepaid, we are forced to create an invoice at the time an order is placed to allow the customer to pay it. Our sales category is therefore skewed, since the sale was actually booked at the time an order was placed, rather then at the time it is shipped, which

    • Zoho Campaigns Account Keeps Shutting Down

      Hey hey, I am completely at a loss here. For months we have been back and forth with Zoho Campaigns Support on Spam Trap hits. Each time they can never provide us with a full list of emails, only 1 here or there. So internally we have setup a integration

    • Need a way to run a client script longet than 10 seconds

      By The Grace of G-D. Hi, Currently, Client Scripts are Timing out at 10 seconds. We have complex logics that needs more time. Can you add a feature request to increase the timeout?

    • Can multiple agents be assigned to one ticket on purpose?

      Is it possible to assign one ticket to two or more agents at a time? I would like the option to have multiple people working on one ticket so that the same ticket is viewable for those agents on their list of pending tickets. Is something like this currently

    • What’s New in 2025 (So Far)

      Hey Recruiters, We’ve wrapped up the first half of 2025 with a few focused enhancements in Zoho Recruit—all aimed at simplifying your day-to-day recruitment tasks. Here’s a quick video that walks you through what’s new so far this year: Here’s a brief

    • Multi-Department Approval for a Single Bill in Zoho Books

      Hello everyone, Hope you're all doing well. I’d like to ask if anyone has found a good workaround for the following scenario in Zoho Books: Let’s say a corporate credit card bill or vendor invoice covers multiple purchases across different projects or

    • Zoho Landing Page "Something went wrong" Error

      Hello, Every time I try to create a new landing page, I receive a "Something went wrong" error with no explanation. I cannot create any new pages, which means we cannot use this application. I did create one landing page successfully over a month ago,

    • Composite items are not seen in zoho commerce

      Composite items are not seen in zoho commerce. Are you scheduled to fix this error?

    • not able to access Zoho from home WIFI

      for some reasone i am not able to access Zoho on my laptop or my iphone while i am connected to my home Wifi, i am able to access these sites both on laptop as well as Iphone and associated apps on any other Wifi as well as when I am on my 4G connection

    • Zoho Books for Service Enterproses

      I would like to know how to use Zoho Books for services such as car rental, travel agency, and hotel services. I notice that Zoho Books is good for goods, but for services, it's very difficult to track the profit or loss on each invoice. I need to capture

    • Email Relay in Zoho Books

      I have set up the email relay in Zoho books and the SMTP test was successful. However, I can't figure out how to sent the POs and invoices via the relay so the copy of the message shows in google workspace sent mail. Any guidance is appreciated

    • E-invoicing/Facturacion Electronica in Peru, SUNAT authority

      Hi Zoho, you are promoting your product very actively in south america as well as in Peru, but since few years there is an obligation for e-invoicing, transmitting information directly to peruvian tax authority SUNAT. Do you have any solution for this?

    • Project Accounting

      Hello Zoho, Can we also bring project accounting in Zohobooks as a ne feature in upcoming developments? This will be helpful for specific business and industries. Thanks

    • Accounts Payable

      hi there  i am using the free version to trial the software. I am working on the acrual basis. When i received a vendor invoice, it gets keyed into the systems as an unpaid invoice as the payment to from the vendor is 14 days. the unpaid invoice does

    • Approval Processes "Record Modification"

      I didn't find any information about the "Record Modification" item in Zoho articles and Tutorials. I see that this item didn't exist a year ago. Help understand how it works, I tested it and didn't see any difference between "all fields" and "no fie

    • How do i add another purchase information heading?

      i would like to add another section right here to enter an amount which then link directly to the cost of goods sold account

    • Help with Zoho CRM API Integration in C# WinForms (Token Generation Issue)

      Hi everyone, I need your help with integrating the Zoho CRM API into a C# desktop application. My goal is to build a WinForms app in Visual Studio that does the following: Fetch the full list of client projects (module: Deals) and display them in a searchable

    • Can we share the URL of My zoho Sheets on other websites?

      Hello everyone? I have sheets on Zoho and I want to share them on other websites like daraz, homeshopping, gepco duplicate bills, etc. I don't have much knowledge about online sharing question forums? I am a student and have a short survey about online

    • Next Page