Kaizen #92 - Bulk Read in PHP SDK

Kaizen #92 - Bulk Read in PHP SDK

Heya! Welcome back to the PHP SDK fold in our Kaizen series.

In this post, we will explore how to use bulk read APIs and how to structure the criteria format for different field data types in PHP SDK based on v4 APIs. This will ease your process of handling large volumes of data in an efficient and streamlined manner. 

What does Bulk Read API do?

The Bulk Read API helps you to fetch large volumes of data that meet specific criteria in a single request. Unlike the GET Records API , which has a limitation of 200 records per call, the Bulk Read API allows you to extract bulk data, 200k records, for data synchronisation purposes. This prevents the need for you to fire multiple API calls which can easily drain your daily credits.

This Bulk Read is asynchronous, thus the result for your request will not be available immediately. So, you will have to either poll the bulk read job status API to know the status or specify a callback URL for Zoho CRM to send notifications regarding the process. 

The CRM system processes your request and returns the results in either a CSV or ICS (for Meetings/Events module) zipped file. To download your result, use the job ID given in the response of bulk read job API .

This entire process can be wrapped into three stages as given below, 
  • Creating a Bulk Read Job 
  • Checking the status of a Bulk Read Job
  • Downloading the CSV/ICS data zip

Create a Bulk Read Job

1. Adding Callback URL

To get notified of the progress and results of the bulk read job, add a callback URL to the request body using the following format. 
$requestWrapper = new RequestWrapper();

$callbackVar = new CallBack();

$callbackVar->setUrl(" your_callback_url ");

$callbackVar->setMethod(new Choice("post"));

$requestWrapper->setCallback($callbackVar);
The method for callback URL is typically set to POST as it helps the client to send the required data along with the url to handle the callback appropriately.

2. Structuring a Query

A query comprises multiple parameters such as your desired module, fields, custom view ID, page value, file-type and criteria.

A criterion is typically a filter/condition used in a query to narrow down the data to your desired set of records. Criteria can include one or more conditions and you can combine them using group operators like 'and' and 'or' to create more complex filtering logic. 

Each condition in the criteria comprises three components.
  • Field - It refers to the field API name of the record, which you want to use for filtering purpose.
  • Comparator - It determines how the value of the specified field has to be evaluated.
  • Value - It represents the value of the field against which the record has to be evaluated.
This helps you to retrieve only the relevant records, thereby optimising the performance and reducing the amount of data transferred.

To enhance the understanding of how to structure a criterion, it is necessary to address these group operators and comparators before delving into it.

Group Operators 

Group Operators are used to perform logical operations on multiple conditions within a query. They help you in grouping multiple conditions together to create complex search criteria.The possible group operators are 'and' and 'or'.
  • and - It specifies that all conditions within the group must be satisfied for a record to be included in the query result.
  • or - It specifies that any of the conditions within the group can be satisfied for a record to be included in the query result.
These operators provide flexibility in constructing queries and retrieve the desired set of records from your CRM system with ease.

Comparators

Comparators are used in a query condition to specify the type of comparison that should be performed between a field and a value. They define the relationship between the field and the value and determine how the records are filtered. Refer to this help document to find the possible comparators with their field datatypes. 

An example of each datatype is given in PHP for your better understanding. 
Data Type
Example
  Number

$conditionVar = new Criteria();
$field = new MinifiedFields();
$field ->setAPIName("Amount");
$conditionVar>setField($field);
$conditionVar->setComparator(new Choice("greater_than"));
$conditionVar->setValue(10000);
  Multi-select 

$conditionVar = new Criteria();
$field = new MinifiedFields();
$field ->setAPIName("owner");
$conditionVar>setField($field);
$conditionVar->setComparator(new Choice("in"));
$owner = ["5545974393001", "5545974393011"]
$conditionVar->setValue($owner);
  DateTime                                   

$conditionVar = new Criteria();
$field = new MinifiedFields();
$field->setAPIName("Created_Time");
$conditionVar>setField($field);
$conditionVar->setComparator(new Choice("between"));
$createdTime = [date_create("2023-05-01T17:58:47+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get())), date_create("2023-06-01T17:58:47+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get()))];
$conditionVar->setValue($createdTime);
  Boolean

$conditionVar = new Criteria();
$field = new MinifiedFields();
$field ->setAPIName("Email_Opt_Out");
$conditionVar>setField($field);
$conditionVar->setComparator(new Choice("equal"));
$conditionVar->setValue(false);
  Lookup

$conditionVar = new Criteria();
$field = new MinifiedFields();
$field ->setAPIName("owner.last_name");
$conditionVar>setField($field);
$conditionVar->setComparator(new Choice("equal"));
$conditionVar->setValue("Boyle");

Structuring Simple Criteria

Below is a query format with a simple criterion of two conditions to filter your records from the given module. 

$criteriaVar = new Criteria();

$criteriaVar->setGroupOperator(new Choice("operatorValue"));

$conditionVar1 = new Criteria();

$fieldVar = new MinifiedFields();

$fieldVar->setAPIName("Field_API_Name");

$conditionVar1->setField($fieldVar);

$conditionVar1->setComparator(new Choice("comparatorValue"));

$conditionVar1->setValue("Field_Value");

$conditionVar2 = new Criteria();

$field = new MinifiedFields();

$field->setAPIName("Field_API_Name");

$conditionVar2->setField($fieldVar);

$conditionVar2->setComparator(new Choice("comparatorValue"));

$conditionVar2->setValue("Field_Value");

$criteriaVar->setGroup([$conditionVar1,$conditionVar2]);

$query->setCriteria($criteriaVar);

$requestWrapper->setQuery($query);

In the above format, the group operator is used for two different conditions.

Following is the json format of this simple criteria.
{
    "query": {
        "criteria": {
            "group_operator": "operatorValue",
            "group": [
                {
                    "comparator": "comparatorValue",
                    "field": {
                        "api_name": "Field_API_Name"
                    },
                    "value": "Field_Value"
                },
                {
                    "comparator": "comparatorValue",
                    "field": {
                        "api_name": "Field_API_Name"
                    },
                    "value": "Field_Value"
                }
            ]
        }
    }
}

Structuring Complex Criteria

To structure a criterion with four different conditions follow the below format.

//top-level group criteria with 2 different groups comprising of 2 different conditions each

$criteria = new Criteria();

$criteria->setGroupOperator(new Choice("operatorValue"));

//group1 with 2 different conditions

$groupVar1 = new Criteria();

$groupVar1->setGroupOperator(new Choice("operatorValue"));

$conditionVar11 = new Criteria();

$field11 = new MinifiedFields();

$field11->setAPIName("Field_API_Name");

$conditionVar11->setField($field11);

$conditionVar11->setComparator(new Choice("comparatorValue"));

$conditionVar11->setValue("Value");

$conditionVar12 = new Criteria();

$field12 = new MinifiedFields();

$field12->setAPIName("Field_API_Name");

$conditionVar12->setField($field21);

$conditionVar12->setComparator(new Choice("comparatorValue"));

$conditionVar12->setValue("Value");

$groupVar1->setGroup([$conditionVar11, $conditionVar12]);

//group2 with 2 different conditions

$groupVar2 = new Criteria();

$groupVar2->setGroupOperator(new Choice("operatorValue"));

$conditionVar21 = new Criteria();

$field21 = new MinifiedFields();

$field21->setAPIName("Field_API_Name");

$conditionVar21->setField($field21);

$conditionVar21->setComparator(new Choice("comparatorValue"));

$conditionVar21->setValue("Value");

$conditionVar22 = new Criteria();

$field22 = new MinifiedFields();

$field22->setAPIName("Field_API_Name");

$conditionVar22->setField($field22);

$conditionVar22->setComparator(new Choice("comparatorValue"));

$conditionVar22->setValue("Value");

$groupVar2->setGroup([$conditionVar21, $conditionVar22]);

//pushing the groups to the top-level group criteria

$criteria->setGroup([$groupVar1, $groupVar2]);

In the above format, two group variables ($groupVar1 and $groupVar2) are created, each representing a nested group of conditions. Both the groups are further assigned to the top-level group variable ($criteria). 

The json arrangement of the above format is given for your clarity.
{
    "query": {
        "criteria": {
            "group_operator": "operatorValue",
            "group": [
                {
                    "group_operator": "operatorValue",
                    "group": [
                        {
                            "comparator": "comparatorValue",
                            "field": {
                                "api_name": "Field_API_Name"
                            },
                            "value": "Field_Value"
                        },
                        {
                            "comparator": "comparatorValue",
                            "field": {
                                "api_name": "Field_API_Name"
                            },
                            "value": "Field_Value"
                        }
                    ]
                },
                {
                    "group_operator": "operatorValue",
                    "group": [
                        {
                            "comparator": "comparatorValue",
                            "field": {
                                "api_name": "Field_API_Name"
                            },
                            "value": "Field_Value"
                        },
                        {
                            "comparator": "comparatorValue",
                            "field": {
                                "api_name": "Field_API_Name"
                            },
                            "value": "Field_Value"
                        }
                    ]
                }
            ]
        }
     }
}

The default file type is CSV. To bulk read the Events module always prefer the ICS file type. Refer to this resource to fetch the custom view IDs, module and field API names. 

Below is a sample code for creating a bulk read job with compound criteria. The criteria follow this arrangement ((1 and 2) or (3 or 4)) of conditions.

<?php

use com\zoho\crm\api\bulkread\BulkReadOperations;
use com\zoho\crm\api\bulkread\CallBack;
use com\zoho\crm\api\util\Choice;
use com\zoho\crm\api\bulkread\Query;
use com\zoho\crm\api\bulkread\Criteria;
use com\zoho\crm\api\bulkread\RequestWrapper;
use com\zoho\crm\api\modules\MinifiedModule;
use com\zoho\crm\api\fields\MinifiedFields;
require_once "vendor/autoload.php";

class CreateBulkReadJob
{
public static function initialize()
    {
        // Add initialisation code
        // Refer to this article for more help
    }
    public static function createBulkReadJob(string $moduleAPIName)
    {
        $bulkReadOperations = new BulkReadOperations();
        $requestWrapper = new RequestWrapper();
        $callback = new CallBack();
        $callback->setUrl("https://www.callback.com/example");
        $callback->setMethod(new Choice("post"));
        $requestWrapper->setCallback($callback);

        //query
        $query = new Query();
        $module = new MinifiedModule();
        $module->setAPIName($moduleAPIName);
        $query->setModule($module);
        $query->setCvid("34770610087501");
        $query->setFields(["Last_Name"]);
        $query->setPage(1);

        //top-level group criteria with 2 different groups comprising of 2 different conditions each
        $criteria = new Criteria();
        $criteria->setGroupOperator(new Choice("or"));
        $criteriaList = array();

        //group1 with 2 different conditions
        $groupVar1 = new Criteria();
        $groupVar1->setGroupOperator(new Choice("and"));

        $conditionVar11 = new Criteria();
        $field11= new MinifiedFields();
        $field11->setAPIName("Last_Name");
        $conditionVar11->setField($field11);
        $conditionVar11->setComparator(new Choice("equal"));
        $conditionVar11->setValue("Boyle");
        
        $conditionVar12 = new Criteria();
        $field12 = new MinifiedFields();
        $field->setAPIName("Owner");
        $conditionVar12->setField($field12);
        $conditionVar12->setComparator(new Choice("in"));
        $owner = array("5545974000000393001","5545974000000393011");
        $conditionVar12->setValue($owner);
        $groupVar1->setGroup([$conditionVar11, $conditionVar12]);

         //group2 with 2 different conditions
        $groupVar2 = new Criteria();
        $groupVar2->setGroupOperator(new Choice("or"));

        $conditionVar21 = new Criteria();
        $field21 = new MinifiedFields();
        $field21->setAPIName("Company");
        $conditionVar21->setField($field21);
        $conditionVar21->setComparator(new Choice("equal"));
        $conditionVar21->setValue("Morlong Associates");
        
        $conditionVar22 = new Criteria();
        $field22= new MinifiedFields();
        $field22->setAPIName("Created_Time");
        $conditionVar22->setField($field22);
        $conditionVar22->setComparator(new Choice("between"));
        $createdTime = array(date_create("2023-04-15T17:58:47+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get())), date_create("2023-06-01T17:58:47+05:30")->setTimezone(new \DateTimeZone(date_default_timezone_get())));
        $conditionVar22->setValue($createdTime);
        $groupVar2->setGroup([$conditionVar21, $conditionVar22]);

         //pushing the groups to the top-level group criteria
        $criteria->setGroup($criteriaList);
        $query->setCriteria($criteria);
        $requestWrapper->setQuery($query);
        // $requestWrapper->setFileType(new Choice("ics")); for Events module
        $response = $bulkReadOperations->createBulkReadJob($requestWrapper);
        //Add your code to handle the response received in $response
        // For more details, refer here.
    }
}
CreateBulkReadJob::initialize();
$moduleAPIName = "Leads";
CreateBulkReadJob::createBulkReadJob($moduleAPIName);
?>

2. Status of a Bulk Read Job

To keep track of the status of your bulk read job, use the id provided in the details section of your bulk read job response. 

Here is a sample code for checking the status of a bulk read job.

<?php

use com\zoho\crm\api\bulkread\BulkReadOperations;

require_once "vendor/autoload.php";

class GetBulkReadJobDetails
{
public static function initialize()        
    {
        // Add initialisation code
        // Refer to this article for more help 
    }

    public static function getBulkReadJobDetails(string $jobId)
    {
        $bulkReadOperations = new BulkReadOperations();
        $response = $bulkReadOperations->getBulkReadJobDetails($jobId);
        //Add your code to handle the response received in $response
        // For more details, refer here.
    }
}
GetBulkReadJobDetails::initialize();
$jobId = "55459743108003";
GetBulkReadJobDetails::getBulkReadJobDetails($jobId);
?>

3. Download Bulk Read Result

To download your bulk read job result, use the job id mentioned in the bulk read job response. Additionally, provide the path of the destination folder where you would like to download the result. The result will be downloaded as a zip file containing CSV/ICS files.
Here is a sample code for downloading a bulk read job result.

<?php

namespace samples\bulkread;

use com\zoho\crm\api\bulkread\BulkReadOperations;

require_once "vendor/autoload.php";

class DownloadResult
{
public static function initialize()
    {
        // Add initialisation code
        // Refer to this article for more help  
    }
    public static function downloadResult(string $jobId, string $destinationFolder)
    {
        $bulkReadOperations = new BulkReadOperations();
        $response = $bulkReadOperations->downloadResult($jobId);
        $streamWrapper = $response->getObject()->getFile();
        fputs(fopen($destinationFolder . "/" . $streamWrapper->getName(), "w"), $streamWrapper->getStream());
        //Add your code to handle the response received in $response
        // For more details, refer here.
    }
}
DownloadResult::initialize();
$jobId = "55459743108003";
$destinationFolder = "/Downloads";
DownloadResult::downloadResult($jobId, $destinationFolder);
?>

We hope you found this post useful and engaging! 

If you have any queries, feel free to drop them in the comments section below or reach out to us directly at support@zohocrm.com. We value your thoughts and eagerly look forward to hearing from you.

Stay tuned for more enriching posts coming your way soon!

Cheers!

    • Recent Topics

    • Unified WhatsApp Number Management in Zoho Desk and SalesIQ

      Dear Zoho Desk Support Team, We are currently utilizing both Zoho Desk and Zoho SalesIQ for our customer support operations. While both platforms offer WhatsApp integration, we are facing challenges due to the requirement of separate WhatsApp numbers

    • Can we have Bills of Material Module ?

      Can we have Bills of Material Module ?

    • Main Ticket Page Customization

      We do not love the ticket list page (right after clicking Tickets menu item) would like options to customize it.

    • Communicating with emojis

      On July 17, we celebrate World Emoji Day! We're a bit late 😐 sharing insights about this day. But we just couldn't let it pass without a mention 😊 because emojis have a meaningful connection with customer service 💬 🤝. We do not want to miss out on

    • Agent Collision Missing from Mobile App

      Please add Agent Collision capabilities to the mobile app.

    • Zia Sentiment and Functionality on Mobile

      Please add Zia sentiment and generative responses to the mobile app. It would be nice to see the ticket sentiment and generate a response back to a user using Zia on my iPhone

    • View Account Attachments on iOS

      Please allow us to view account attachments on the mobile iOS app!

    • How do I run a PnL by Sales Person?

      I am trying to run a PnL by sales person but am not seeing the option do so. All I need to know (per salesperson) is revenue, cost of goods, gross profit.

    • View Contracts and Support Plans on Mobile

      We would like to be able to see contracts and support plans from the mobile app on iOS!

    • Why is Zoho Meeting quality so poor?

      I've just moved from Office 365 to Zoho Workplace and have been generally really positive about the new platform -- nicely integrated, nice GUI, good and easy-to-understand control and customisation, and at a reasonable price. However, what is going on

    • App like Miro

      Hi all, is there a way to have a interactive whiteboard like in Miro? We want to visualize our processes and workflows in an easy way.

    • Loan repayment Entry

      While receiving loan, i does following steps in My Zoho books. 1. Create "Loan & Advance " Account as Parent Account under Long Term Liabilities. 2. Create another account For Example "Mr. ABC's Loan as Child account under the parent account. Now: In

    • Quotes module send email reverted back into 2022??

      Our Zoho CRM PLUS quotes, sales orders, invoice modules is showing us an email composer from 2022. We cannot send emails and its been a real pain. I tried clicking the new version over there but it doesnt seem to do anything. Any help is welcome. th

    • Workflow Condition - how do check that a date / time value is in the past?

      Hello, I'm got a workflow that runs a function when records reach their 'Effective Date / Time', but sometimes records are created after the 'Effective Date / Time' so I have another workflow that checks for records which needs to be processed immediately.

    • Pre filling SignForm field values by URL field alias's in Zoho Sign

      Hi, Does anyone know if it's possible to pre fill the field values of the SignForm by using field alias's like you can in Zoho forms? To be more specific, I want to be able to change the SignForm URL to include some information like this: Before : https://sign.zoho.eu/signform?form_link=234b4d535f495623920c288fc8538cb9e6db03bbfd44499b63f3e5c48daf78f44bc47f333e2f5072cc1ee74b7332fe18b25c93fab10cb6243278d49c67eacbf30bbe5b6e1cc8c6b2#/

    • How to Split Payout in Zoho Books (Without Using Journal?)

      Hi, I'm trying to properly record payouts in Zoho Books. The issue is that each payout is a combination of sales and expenses (fees). When I try to categorise the payout transaction from the Banking tab, I can only split the transaction using income-type

    • Payment Schedule

      Please add the ability to create a payment schedule. The other options, like retainer invoices or two invoices, do not work for the customer.  We invoice a client and need to be able to show them everything they owe in one invoice, and when each payment

    • Which pricing system do you think would work best for us?

      Imagine we’re selling strictly wholesale. We’d rather not publish unit prices; instead, we quote customers case-by-case. To spur larger orders, we’re considering a transparent discount ladder—say: $0 – $999: 0 % $1,000 – $1,999: 5 % $2,000 – $4,999: 10

    • Can't Remove Payment Gateway

      I am getting the error "Settings cannot be cleared as some of the transactions are still in progress." when trying to remove the PayGate payment gateway which I was unable to get working. I am now using paystack and I want to remove Paygate.

    • Sync specific Zoho Inventory Warehouses to Zoho Commerce

      As said in the title, we would want to only sync stock from one warehouse of Zoho Inventory to the Zoho Commerce item stock. We have a 2 warehouses in different countries and the way that Zoho Commerce works (It takes stock from ALL WAREHOUSES EVERYWHERE

    • Weekly Tips : Automatically clean clutter with Junk cleanup interval

      If you regularly receive many unwanted or spam emails, your Spam folder can quickly fill up and start taking up valuable storage space in your Zoho Mail account. Instead of manually clearing it every few days, you might find it helpful to enable automatic

    • Any solution for getting portal users list in deluge or in widget

      Hi Team, Has anyone able to find the solution to get portal users list in deluge or in zoho creator widgets? Thanks, Payal

    • The Grid is here!

      Hey Zoho Forms Community! 👋 We’re thrilled to announce the launch of a feature that’s been on your wishlist for a while: Grids What is Grids? Grids let you place form fields side by side in multiple columns to create a more concise and organized form

    • Steuerberater der Zoho benutzt in Deutschland

      I write in English because the issue is related to German regulations. Wir sind ein Unternehmen, welches aktuell keine Pflicht zur doppelten Buchführung hat. Aktuell bucht unser Steuerberater jeden Beleg, auch unsere Auslagen. Wir würden dies gerne selbst

    • GraphQL in new Send Webhooks feature

      Hello, is it possible to use GraphQL apis in the new Send Webhooks feature?

    • # 2 Why do we need a billing system when accounting covers billing?

      In today's evolving financial tech stack, businesses use a mix of tools to manage their day-to-day operations, from invoicing to full-fledged accounting. While accounting platforms typically come with built-in invoicing features, specialized billing systems

    • How to insert an Excel/Zoho Sheet table in a chat?

      Hello, is there a way to paste an excel/zoho sheet table to a conversation without loosing table lines. I tried to paste a piece of a table and all the columns and rows were gone. How to easily paste a table without a need of sending a file? Katarzy

    • Mass Update Application Status

      How to update application statuses of Multiple Applications at once? Is that possible? If not then why please consider adding it It can save hours of manual work Thats the only Option I see

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

      Hi there! Wondering how to bridge the gap between digitized customer service and business paperwork? Attend our free webinar to learn how you can do this by connecting Zoho Sign, our digital signature app, with Zoho Desk, our online customer service help

    • Mail Search Not Working

      Hello, Mail search is not working at all. I've tried Chrome and Mozilla. I can try and search for an exact term, or even an email that is 1st in my email list. All search does is sit and spin, or it comes up with no results. I've also tried it on my android

    • Cannot Send Email to a Gmail Account

      Hello, I have a zoho-hosted email account, alex@chirochannelnetwork.com that has trouble sending to gmail accounts.  But not all gmail accounts, only some of them. I've tried to figure this out with clients, and they don't appear to be going into their

    • Unblock ME

      info@pentekykloi.gr Unable to send message;Reason:554 5.1.8 Email Outgoing Blocked. Learn more. I purchase additional storage

    • Cannot Print Landscape with Zoho Sheet

      I am noticing that when using the Zoho Sheet desktop for Mac, that even when selecting landscape as the print option, once you choose "Print", a second system dialog opens that automatically makes the view portrait again, and does not allow printing in

    • Power of Automation : Enhancing custom date field calculations by excluding Weekends and Holidays

      Hello Everyone, A Custom function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:

    • Stock count by bin location

      Is there a configuration to make a stock count by bin or area and not by product. these is useful to manage count by area Regards

    • Temporary Outage in Zoho Cliq Affecting US Users – July 23, 2025

      We experienced a service disruption in Zoho Cliq that impacted core functionality for users in the US region. The issue occurred between Jul 23, 2025, 06:54:00 PM IST and 07:13:13 PM IST, lasting approximately 19 minutes. To restore service stability,

    • portal.assignUserInProfile - Não esta adicionando

      Estou encontrando problema com este comando portal.assignUserInProfile Não esta incluindo o usuário no portal Alguém pode me dizer o que pode ser thisapp.portal.assignUserInProfile("teste@gmail.com","Customer");

    • CRM emails vs Campaigns

      Please help me understand this. I am having a difficult understanding of "Campaigns" sent through CRM (real emails) or Zoho One (blast "potentially junk" emails) This is what I currently think emails sent via CRM are "real" emails sent through linked real personal email accounts and therefore are more likely to get delivered.  We use this for critical updates for our "Approved " accounts and certain other preferred statuses emails via Campaigns are sent through the Zoho server (like MailChimp, Campaign

    • Setting up property management in Zoho Books

      Hi, I run a property management business that manages property complexes. There are multiple owners, some owning more than one property on the same complex. My role is to manage the fees they pay for maintenance of common areas, such as the swimming pool

    • Reverse proxy

      We have a web application in the creator platform. When I launch a particular DNS, I would like that DNS to redirect to the web page of the application in creator app. Has anyone achieved it and if yes, please share how to do it.

    • Next Page