Get the Status of the Bulk Read Job
Purpose
To get the details of a bulk read job performed previously.
Endpoints
Request Details
Request URL
{api-domain}/crm/bulk/v2.1/read/{job_id}
where job_id is the unique ID of the bulk read job.
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
scope=ZohoCRM.bulk.read
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}
Possible module names
leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, and custom
Possible operation types
ALL - Full access to related records
READ - Get bulk read job
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/bulk/v2.1/read/3652397000000646004"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Copied//Get instance of BulkReadOperations Class
$bulkReadOperations = new BulkReadOperations();
//Call getBulkReadJobDetails method that takes jobId as parameter
$response = $bulkReadOperations->getBulkReadJobDetails($jobId);Copied<?php
class GettheStatusoftheBulkReadJob{
public function execute(){
$curl_pointer = curl_init();
$url = "https://www.zohoapis.com/crm/bulk/v2.1/read/3524033000006003003";
$curl_options = array();
$curl_options[CURLOPT_URL] =$url;
$curl_options[CURLOPT_RETURNTRANSFER] = true;
$curl_options[CURLOPT_HEADER] = 1;
$curl_options[CURLOPT_CUSTOMREQUEST] = "GET";
$headersArray = array();
$headersArray[] = "Authorization". ":" . "Zoho-oauthtoken " . "1000.7b0edXXXXXXXf0997f93ed53.daebf12XXXXXXX03247e89e302";
$curl_options[CURLOPT_HTTPHEADER]=$headersArray;
curl_setopt_array($curl_pointer, $curl_options);
$result = curl_exec($curl_pointer);
$responseInfo = curl_getinfo($curl_pointer);
curl_close($curl_pointer);
list ($headers, $content) = explode("\r\n\r\n", $result, 2);
if(strpos($headers," 100 Continue")!==false){
list( $headers, $content) = explode( "\r\n\r\n", $content , 2);
}
$headerArray = (explode("\r\n", $headers, 50));
$headerMap = array();
foreach ($headerArray as $key) {
if (strpos($key, ":") != false) {
$firstHalf = substr($key, 0, strpos($key, ":"));
$secondHalf = substr($key, strpos($key, ":") + 1);
$headerMap[$firstHalf] = trim($secondHalf);
}
}
$jsonResponse = json_decode($content, true);
if ($jsonResponse == null && $responseInfo['http_code'] != 204) {
list ($headers, $content) = explode("\r\n\r\n", $content, 2);
$jsonResponse = json_decode($content, true);
}
var_dump($headerMap);
var_dump($jsonResponse);
var_dump($responseInfo['http_code']);
}
}
(new GettheStatusoftheBulkReadJob())->execute();Copied# Get instance of BulkReadOperations Class
bro = BulkRead::BulkReadOperations.new
# Call get_bulk_read_job_details method that takes jobId as parameter
response = bro.get_bulk_read_job_details(job_id)Copiedrequire 'net/http'
require 'json'
class GettheStatusoftheBulkReadJob
def execute
parameters ={}
parameters["job_id"]="3524033000006027001"
query_string = parameters.to_a.map { |x| "#{x[0]}=#{x[1]}" }.join('&')
url= "https://www.zohoapis.com/crm/bulk/v2.1/read/3524033000006003003"
url += '?' + query_string if !query_string.nil? && (query_string.strip != '')
url = URI(url)
req = Net::HTTP::Get.new(url.request_uri)
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
headers={}
headers["Authorization"]="Zoho-oauthtoken 1000.dfa7XXXXXXXXXXXXXXXXXX84f9665840.c176aeXXXXXXXXXXXX13f3d37a84d"
headers["Content-Type"]="application/json"
headers&.each { |key, value| req.add_field(key, value) }
response=http.request(req)
status_code = response.code.to_i
headers = response.each_header.to_h
print status_code
print headers
unless response.body.nil?
print response.body
end
end
end
GettheStatusoftheBulkReadJob.new.executeSample Response: For Job ADDED
Copied{
"data": [
{
"id": "4150868000004717002",
"operation": "read",
"state": "ADDED",
"query": {
"module": {
"id": "4150868000000002179",
"api_name": "Contacts"
},
"page": 1
},
"created_by": {
"id": "4150868000000225013",
"name": "Patricia Boyle"
},
"created_time": "2021-02-22T18:00:28+05:30",
"file_type": "csv"
}
]
}Sample Response: For Job QUEUED
Copied{
"data": [
{
"id": "4150868000004717004",
"operation": "read",
"state": "QUEUED",
"query": {
"module": {
"id": "4150868000000002179",
"api_name": "Contacts"
},
"page": 1
},
"created_by": {
"id": "4150868000000225013",
"name": "Patricia Boyle"
},
"created_time": "2021-02-22T18:21:17+05:30",
"file_type": "csv"
}
]
}Sample Response: For Job IN PROGRESS
Copied{
"data": [
{
"id": "4150868000004717004",
"operation": "read",
"state": "IN PROGRESS",
"query": {
"module": {
"id": "4150868000000002179",
"api_name": "Contacts"
},
"page": 1
},
"created_by": {
"id": "4150868000000225013",
"name": "Patricia Boyle"
},
"created_time": "2021-02-22T18:21:17+05:30",
"file_type": "csv"
}
]
}Sample Response: For Job COMPLETED
Copied{
"data": [
{
"id": "4150868000004717004",
"operation": "read",
"state": "COMPLETED",
"result": {
"page": 1,
"per_page": 200000,
"count": 102,
"download_url": "/crm/bulk/v2.1/read/4150868000004717004/result",
"more_records": false
},
"query": {
"module": {
"id": "4150868000000002179",
"api_name": "Contacts"
},
"page": 1
},
"created_by": {
"id": "4150868000000225013",
"name": "Patricia Boyle"
},
"created_time": "2021-02-22T18:21:17+05:30",
"file_type": "csv"
}
]
}Response Structure
- operationstring
Specifies the type of action the API completed. Sample - "operation" : "read”.
- created_byJSON Object
Specifies the ID and Name of the user who initiated the bulk read job. Sample - "created_by": { "id": "1000000031045", "name": "Patricia Boyle" },
- created_timeISO8601
Specifies the time period of when the bulk read job was initialized.
- statestring
Specifies the current status of the bulk read job. Example: "state": "ADDED", "QUEUED", "IN PROGRESS", or "COMPLETED".
- queryJSON Object
Specifies the "query" provided by the user when creating the bulk read job. The attributes are the same as in the Request JSON, with "modules", "cvid", fields", "criteria" and "page".
- idString
Specifies the unique identifier of the bulk read job. Sample - "id": "1000010760002".
- resultJSON Object
It is available only after the completion of the job. Please refer to the below section for information on the "result" JSON object.
"result" Properties
- pageInteger
Describes the range of the number of records exported. If the "page" is one, then the number of records would be between 1 - 200,000. If it's "two", then the records from 200,001 - 400,000 will be taken for export.
- countInteger
Specifies the actual number of records exported. Sample - "count": 14567
- download_urlString
Specifies the url which contains the CSV file. User can send a GET request with your api domain attached to the download URL to download the file. Sample - "/crm/bulk/v2.1/read/2883756000001275012/result".
- more_recordsboolean
The "more_records" key in the response can be used to detect if there are any further records. You can change the value of "page" key for additional export jobs.
To know about the Bulk Read API limits, go here.
Possible Errors
- INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to request URL section above. - OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have ZohoCRM.bulk.read or ZohoCRM.modules.{module_name}.READ. Create a new client with valid scope. Refer to scope section above. - NO_PERMISSIONHTTP 403
Permission denied to read
Resolution: The user does not have permission to read records. Contact your system administrator. - INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in Server. Contact support team. - INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section above. - AUTHORIZATION_FAILEDHTTP 400
User does not have sufficient privilege to read.
Resolution: The user does not have the permission to read records. Contact your system administrator. - RESOURCE_NOT_FOUNDHTTP 404
The requested resource doesn't exist.
Resolution: The job ID specified is invalid. Specify a valid job ID.
Sample Request: For the job with cvid and Criteria
Copiedcurl "https://www.zohoapis.com/crm/bulk/v2.1/read/554023000000568002"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Sample Response: For Job Completed
Copied{
"data": [
{
"id": "4150868000004717006",
"operation": "read",
"state": "COMPLETED",
"result": {
"page": 1,
"per_page": 200000,
"count": 0,
"download_url": "/crm/bulk/v2.1/read/4150868000004717006/result",
"more_records": false
},
"query": {
"fields": [
"Last_Name",
"Owner",
"Owner.last_name",
"$converted",
"Lead_Source",
"Lead_Status",
"Company",
"Email",
"Mobile",
"Created_Time"
],
"module": {
"id": "4150868000000002175",
"api_name": "Leads"
},
"criteria": {
"group": [
{
"field": {
"id": null,
"api_name": "$converted"
},
"comparator": "equal",
"value": false
},
{
"group": [
{
"field": {
"id": "4150868000000002595",
"api_name": "Last_Name"
},
"comparator": "equal",
"value": "Patricia"
},
{
"field": {
"id": "4150868000000002599",
"api_name": "Email"
},
"comparator": "equal",
"value": "patricia.b@zylker.com"
}
],
"group_operator": "and"
}
],
"group_operator": "and"
},
"page": 1,
"cvid": "4150868000000087501"
},
"created_by": {
"id": "4150868000000225013",
"name": "Patricia Boyle"
},
"created_time": "2021-02-22T18:24:38+05:30",
"file_type": "csv"
}
]
}