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

    • Education Zoho User Group (ZUG) virtual meetup featuring Zoho Sign

      Hi there! The educational sector often faces the hassle of handling extensive paperwork, which leads to increased operational costs. A digital signature solution like Zoho Sign can help you modernize your processes, go fully digital, and seamlessly collect

    • Troubleshooting Delays in Zoho CRM Automation Workflows for Lead Status Updates

      Dear Zoho Community, I am refining a sales pipeline in Zoho CRM, implemented in May 2025, to enhance efficiency for a small business managing client leads. While the CRM effectively tracks leads, I am encountering delays in automation workflows that update

    • 📣 [Webinar] Spikra shows how businesses leverage Zoho Bookings to increase revenue

      [Webinar] Spikra shows how businesses leverage Zoho Bookings to increase revenue Hi all, Service-based businesses need to be on top of their client experience game to stay ahead. Spikra, one of our Advanced Zoho Partners, has been helping businesses deliver

    • Kaizen #172 - Leveraging the 'crmAPIResponse' Object in Queries

      Hello everyone! Welcome back to another week of Kaizen! We released the Queries feature sometime back and hope you have tried it out. A little gist about this feature before we move on to our post. Zoho CRM's Queries feature enables dynamic data retrieval

    • transforming 1D tables to 2D and the other way round

      Does Dataprep have tools to convert 1D tables to 2D tables and the other way round? The actions that are commonly called "pivot" and "melt". What I mean is transitioning between these two kinds of table: 2D id ____ name ____ surname ____ age 00 ____ Matt

    • How I Migrate data from one SharePoint Tenant to another

      I want to perform SharePoint tenant to tenant migration, but the problem is I don't know how to do so. I’ve heard about different SharePoint Migrator, but I’m not sure which one is the best for this type of migration. Any guidance would be really he

    • Rebrand your CRM with the all-new custom domain mapping setup

      UPDATES TO THIS FEATURE! 19th Jan, 2024 — Custom domain mapping has been made available for portal users in Zoho One and CRM Plus. 23rd June, 2023 — Custom domain mapping has been made available for all users, in all DCs. Hello everyone! We are elated

    • authentication

      We cannot connect via IMAP. We are receiving the following error: Error: You are yet to enable IMAP for your account. Please contact your administrator (Failure)

    • Bad User: Authenticated but not connected

      Zoho CRM cannot send/receive emails and it appears as if it may be an api configuration change either via Zoho or MS. Does anyone have information on how to fix this error message? I am admin on all my accounts. Zoho and MS are blaming each other.

    • Edit email address that appears on invoice

      Hi How do I change the email address that appears on invoices, it is showing the email address that i used to sign up to zoho with but I want to change it to another email address that we use for accounts. also is there a way to edit the position of a

    • Zoho Tasks - Add Sorting by Priority

      We are able to Group by and Filter by Priority but for some reason we can't Sort by Priority on the Task lists. Please allow for sorting by priority if the current view is not grouped by priority.

    • customize payment page

      Is there a way to customize, other than the theme colour, the payment page that customers are taken to from invoices? I can't seem to find a way. I just don't like the formatting of the current page and would like to make it look better. I've looked at

    • Zoho People > Candidate Form > error Editable Primary Lookup is needed to set add permission

      Hello All I have try to turn on the add feature in the candidate form It show the error Editable Primary Lookup is needed to set add permission What is missing from my side?

    • 6 time-saving tips for working with tables in Zoho Writer

      Tables have always been the best way to represent data. They help you structure and categorize information systematically and present them in a simpler way. While tables in Zoho Writer are easy to implement, some tasks might not be that obvious.  Here are some time-saving tips to help you work better with tables in Zoho Writer:    1. Insert Multiple Rows / Columns in a Table Adding more rows and columns is the most common action performed while working with tables. Instead of using the Table tab,

    • Add Built-in "Partner Finder" / "Contractor Directory" Tab to Zoho Desk Help

      Hi Zoho Team, We hope you're doing well. We would like to request a new feature for the Zoho Desk Help Center: A built-in, configurable "Partner Finder" / "Contractor Directory" tab or section, similar in concept to your own Zoho Partner Finder at: 🔗

    • Can't get sender adress to work

      Hi, I am having some trouble getting the sender adress to work for responses on tickets. I would like to configure a sender adress that is different from the zohodesk emailadress that is normally used. These are the steps I have followed: 1. Add a new

    • Question Regarding Deleted Reports in Zoho Desk Analytics

      Dear Zoho Desk Support Team, I hope this message finds you well. We have a question regarding the Analytics module in Zoho Desk, specifically related to deleted reports/dashboards. We would like to understand the following: Is there a recycle bin, recovery

    • Add an option to start zobot when user clicks the Chat with Us button

      I would like to have an option to start the zobot when user clicks on "Chat with us" button when chat widget is maximized that way visitors could see first the homepage and decide which channel they would like to use to connect, or to see the quicke help

    • Zoho Books - Feature Request - Provide "Show PDF View" toggle on Invoice records

      I have noticed it is possible to activate or deactivate the PDF preview on some records but not all. This would be very helpful on Invoices when a custom template is being used and the PDF preview does not represent the output file. Not available on:

    • Incorrect Handling of XLSX data

      Trying to import an XLSX schedule of bills into Zoho Books I ran across the problem of date formatting. To replicate: Build a CSV file with bill dates in whatever format you like and import it - this should work if you match the "dd/MM/yyy" etc. format

    • Disable Smart Filters By Default

      The smart filters "feature" is causing confusion for Zoho Mail users. New emails should be delivered to the inbox unless they have specifically opted to redirect them somewhere else. People don't understand that new emails might be waiting in a random

    • Adding Columns to Reports

      Hi, Is it possible to choose fields to be added as columns in the reports? Thank you.

    • How do I automatically assign the project owner for all tasks in Zoho Projects?

      I have been researching for days on how to automatically assign all the tasks to the project owner on creation of the project in Zoho Projects. I have been having to go in and manually change all the task owner from 'unassigned' to the owner of the project

    • CRM Kiosk - Action for GetRecords

      I have a Kiosk screen with GetRecords and want to use the selected records in a custom function. My particular case is to set a lookup value on the selected records. Generally speaking though, I want to work with the selected records in a function. I

    • Extract Archived Projects using Zoho Projects API

      In my organization we archive the projects when they are already completed, charged, invoiced, so that only those that are still pending process remain active. I need to access all projects (active and archived) from an external system, but the API v3

    • Email for customer to provide payment information

      Is there a way for customers when you set up a subscription to get an email that prompts them to put in their billing information to start their subscription? Also, can you show the subscription in their portal?

    • Unable to display field label from a hidden Single Line Textbox in Description

      Hi folks, I'm unable to display my hidden field, e.g. ${zf:SingleLine4} , in my description. I'm pre-filling this hidden Single Line Text box via "Field Alias - Pre-fill URL" settings. I noticed that my decimal form fields work, e.g. ${zf:Decimal}, and

    • Lookup fields

      Is there any way to add Lookup fields to Zoho FSM -- I do not see the option but I see default lookup fields in different modules

    • Zoho Analytics - Bill Table

      Hi I am new to Zoho and mainly work in Books. Recently learned of Zoho Analytics and am exploring it to create reports that would be useful for me. For example, I want to create a bills cash forecast by week for cash flow planning. When I start to create

    • Creating a tax - amount table in Analytics

      Hi everyone, I would like to create a report in Zoho Anayltics that creates the tax and amounts in a table. I have been able to create a report that shows me all the tax accounts, but I can't get it combined with the amounts of the accounts. Is there

    • Is it possible to do custom domains on test accounts that use saml setups?

      In Zoho Billing, Is it possible to do custom domains on test accounts that use saml setups for the customer portal?

    • I’m facing an issue while trying to upload a PDF file to a custom file upload field within the Leads module via the Zoho CRM API.

      Hi Zoho Team, I’m facing an issue while trying to upload a PDF file to a custom file upload field within the Leads module via the Zoho CRM API. I am able to manually upload a PDF into this field through the UI. I am also able to upload files as attachments

    • No chat option

      Chat option is not available in Android app.

    • How to add custom templates in zoho sheets mobile

      How can I add custom templates in Zoho spreadsheet mobile?

    • Order Items

      Hi .. We have to implement orders with line but each line should have a separate record and not as a subform, does anyone have experience with that kind of solution what is the best practice for that kind of thing Thanks

    • Trello: Invalid Client - Client ID passed does not exist

      Hello, I am trying to authorize the Zoho CRM power-up in Trello but always land on the following page: I tried adding a trello client to the Zoho API console but this generated a different client ID to the one in the link of the page in the above picture.

    • Zoho Sprints - Q2 updates for 2025

      Hello everyone! We’re excited to share the latest updates from Zoho Sprints for Q2 2025! This quarter, we rolled out a few highly-requested features designed to enhance collaboration and time management across your projects. Here's a look back at the

    • CRM Email Insights Not Working - Status not Changing

      I used to be able to see if a customer opened/read an email in CRM, but I no longer get those status changes inside their record. I have everything enabled and I am sending the email from CRM. The experience center has the status' enabled as well. Any

    • The use of Ticket statuses

      When your support team mark a ticket "Closed" before I had a time to check what your team has done on the ticket - I have to consider this as you consider the ticket closed even if I dont consider it closed. Which automatically produce a negative sentiment.

    • "Replace" an existing version of CRM

      Hi all, I have a question, I saw an article about this once, but I now cannot find it. I am working with a client who has had their CRM in Zoho One built and extensively modified. But it is non-functional now, and rather than try and unpick the system,

    • Next Page