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

    • Quickbooks invoice with Zoho Creator

      Is it possible to push data from Zoho Creator directly to an invoice on QuickBooks? If so, where can I find information on how to do this?

    • Help: Capture full page URL in hidden field when same Zoho Form is embedded on multiple pages (iframe)

      Hi all, Goal Use one Zoho Form across multiple pages and record the exact page URL (incl. subdomain + path + hash) where the user submitted it. Example pages: https://www.example.com/cargo/ https://www.example.com/cargo/containers/#contact https://cargo.example.com/auto/

    • Automatically Populate fields - HELP!

      There have been many discussions on this but I still can't seem to get it to work for me. I am trying to create a lookup field and have other fields automatically populate. Based on the instructions in the Help Center, I should be using the "on user input". It's just not working, here is the layout...   Both forms are in the same application. Current form is called Add Note, form to fetch records from is called Add Client. Lookup field is called Select_Client_ID related field in fetch form is called

    • Push notifications to portal users

      Hi all, it is possible to send push notifications to portal users?

    • Rename the attachment from record template pdf in the sendmail deluge script

      Hello Zoho, I urgently need a feature to rename record templates that I send via the sendmail feature. The program I created sends emails to clients with an invoices that have been created in the invoice database. If the user selects 3 invoice numbers,

    • Alt Text On Multiple Images

      I'm using Zoho Social to post to a charity website. Often the posts have multiple images, but it seems there is only one field for Alt Text. Does that mean I can only include it for the first image? Or is there a way to add alt text for all the imag

    • [SOLVED] Getting 401 when trying to download ticket attachment via API

      I'm able to use the API just fine to access ticket content. But I cannot download ticket attachment, keep getting 401 Client Error. Example: https://desk.zoho.com.au/api/v1/tickets/{ticket_id}/attachments/{attachment_id}/content?orgId={org_id} For headers,

    • Zoho project – Workdrive integration.

      Hello everyone, I was wondering something, we did the Zoho projects integration with Zoho Workdrive but nowhere during this integration we could set the location of the folders that would be automatically created in Workdrive. As I understand it, it creates

    • Scriptを埋め込みたくてOn User Inputを探しているのですが・・・

      編集モードで、Scriptを埋め込みたい項目を選択し、「項目のプロパティ」パネルで、その下のほうに「フィールドアクション（Field Actions）」という見出しがあると聞いたのですが、そもそも、それが見つかりません。そのために、On User Inputなどのイベントが選べません。 画面の英語を日本語に訳しているためにわけわからん状態になっているのかも知れませんが、わかる方、いらっしゃいますか？

    • Problem with cloud query exceeded

      When making a call I get this error, It is associated with a function in node that calls external APIs This is the code //tokenConsultar = thisapp.ObtenerToken(); //input.token = tokenConsultar.get("output").toMap().get("token");

    • Showing Total of Funnel Chart Legend (With Values) Items

      Hi, We are using the funnel type chart for displaying our zCRM sales pipeline stages and associated sum of deals in each stage.  We have configured the legend to show the associated value (Deal Amount (Sum)) for each stage adjacent to the legend items (Stages). Is there a way to display the total of the values in the same chart?  For example, at the bottom of the legend or maybe as a #merge placeholder in the legend title?

    • How to Convert VCF Contacts to CSV using Excel

      Many users switch from traditional address books to digital formats like vCard and CSV. These formats allow users to easily manage their contacts. However, a difficulty comes when you need to transfer your contact information to another application or

    • Field authorization for Linking module in Zoho CRM portal

      Hi guys! Currently building a customer portal for one of my clients, and I ran into a bit of a roadblock while using a multi-select lookup field. The issue is that there is no way to hide or define access in the linking module created by this multi-select

    • Kaizen #63 - Layout Rules in Zoho CRM

      Hello and welcome to another week of Kaizen! This week, we will be discussing Layout Rules in Zoho CRM. If you need to modify the layout of a module based on user inputs, or to show or hide sections based on the value of a specific field, we have got

    • Zoho CRM Portals - allow access per account

      Hello all, I am trying to set up a portal for our customer but I seem to be hitting an obstacle and I am not sure if it is my problem or a limitation in the software. So basically the way I understand the portal Contact Email > Each Record or Related

    • Android - Writer não acentua em Português com teclado bluetooth

      Gosto muito do Zoho, tanto o Note quando o Writer. Infelizmente, o Writer sofre de um problema sério: ao usar um teclado bluetooth, forma mais cômoda de lidar com um processador de texto, os acentos (todos!) da Língua Portuguesa não são aceitos. Todos

    • Set File Upload fields as mandatory

      Currently the CRM for some reason lacks the ability to set a file upload field as mandatory So we have an issue We have a requirement that before a Deal stage is set as Deal is Won the member needs to upload a file Now for some weird reason in Zoho I

    • Editing HTML in Zoho CRM Email Template

      I am trying to create a template within the CRM email option, but need to be able to use custom HTML. There does not seem to be a way to do so.

    • Ability to CC on a mass email

      Ability to CC someone on a mass email.

    • How to make attachments mandatory

      I want the user to be unable to mark an opportunity as Closed – Won if it doesn’t have any attachments. I’ve already tried client scripts and functions, but nothing worked.

    • SLA Ticket Report

      From data to decisions: A deep dive into ticketing system reports Service level agreement (SLA) ticket reports in a help desk system are crucial for ensuring that services are delivered according to established commitments. They help maintain accountability

    • Zoho Backstage - PCI Compliance / Web Security

      I have a couple of questions related to Backstage and payment processing.... 1. my purchasing division is not giving approval to use Backstage yet because of some security issues. In order for us to take payments via a payment gateway like Authorize.net

    • Zoho Tables August 2025 Update: Faster and Smoother

      We’ve been working behind the scenes to make Zoho Tables faster, lighter, and more reliable. Here are the highlights: Faster Response Times Optimised the way responses are generated. Reduced memory consumption by 20–25%, leading to smoother performance

    • Video Upload from app says "unsupported aspect ratio" but is verified to be correct.

      I and my social media person are experiencing a problem where Social will not accept video uploads to Instagram. The error we receive is "unsupported aspect ratio" but looking directly at the file in question we see that the width and ratio both match

    • Disposable Email Addresses

      Dear zMail Team, Can you also bring out a few disposable email addresses for each accounts? That way occasional registrations and imminent spam from them can be largely solved right? ---- Deepak Vasudevan http://thamizhththendral.blogspot.com/

    • Zoho sheet - Zoho expense

      I want to schedule to create an expense using Zoho Sheet and flow. That is the EMI that I pay on a particular date to the bank and should be itemised, like principal and interest on the loan. Can someone help me in this regard??

    • Ability to configure a schedule/shift for each user and/or crew in Zoho FSM

      Hello, In our team of Field Agents, we have different shifts. Some field agent always work from 7:00 AM to 4:00 PM while others work the evening shift like 4:00 PM to 11:00 PM. Sometime shift are on weekdays only or on weekend. It would be great to be

    • Free webinar: Streamlining customer service paperwork with the Zoho Sign extension for Zoho Desk

      Hello Everyone! Have you been wondering about bridging the gap between digitised customer service and business paperwork? Join our free webinar to learn how you can do this by connecting Zoho Sign, our digital signature app, with Zoho Desk, our online

    • Zoho Books | Product updates | July 2025

      Hello users, We’ve rolled out new features and enhancements in Zoho Books. From plan-based trials to the option to mark PDF templates as inactive, explore the updates designed to enhance your bookkeeping experience. Introducing Plan Based Trials in Zoho

    • Mail Search should allow grouping by conversation like Gmail.

      Having switched from gmail I have found the search function hard to use. Mostly because mail is not grouped by conversation in search. If I search for a word when looking for a conversation had with someone then sometimes 10 emails will come up from the

    • Improve Zoho Learn updated article notifications

      I noticed today while updating an article, that the notification users get says "[User Name] has published article [Article Name]..." My feedback to the product team is that it would be really helpful for an end user, if the system notification differentiated

    • Safari Support

      Safari, the world's second largest browser, zoho desk does not officially or fully support. That needs to change.

    • Can I get images from an "Image Upload" field in a webhook?

      I want to send images from 2 "image upload" fields via a webhook. Is this possible?

    • Ticket closure notification - all contacts cc'd on email thread

      Hello, If a client sends an email to our service desk and cc's in other people that work at the same company - so that they are in the loop of the service request. When the we close the ticket, only the ticket owner (person who emailed us - which created

    • Inactive account cleanup policy for Zoho Sign

      Zoho Sign reserves the right to delete accounts that are license free and inactive for more than 120 days. The account deletion will be initiated only after the user receives prior email notice about possible data deletion and how to backup the data.

    • Missde API documentation for Sales Receipt

      Hi! I noticed that the Sales Receipt endpoint is not currently listed in your API documentation (https://www.zoho.com/books/api/v3/introduction/). Could you please provide any available temporary documentation for this endpoint, along with a detailed

    • Multi-currency in Zoho CRM Forecast and Reports

      As a company we have branches in 4 different countries with as many different currencies. Our Sales Teams would like to work with their local currency as much as possible. The Forecast module using only 1 currency is practically usable only by the sales

    • How to select from pricebook when creating a salesorder or quote

      I am creating a sales order and when selecting the Products I do not see any where to select from pricebooks. How do i associate this to my orders?

    • Proposal for Creating a Unique "Address" Entity in Zoho FSM

      The "Address" entity is one of the most critical components for a service-oriented company. While homeowners may change and servicing companies may vary, the address itself remains constant. This constancy is essential for subsequent services, as it provides

    • I cannot find my older documents from 2024 and 2023

      I cannot find my older documents from 2024 and 2023.

    • Next Page