Create Bulk Read job (Bulk Export)

Purpose

To create a bulk read job to export records.

Request URL

https://recruit.zoho.com/recruit/bulk/v2/read

Request Method

POST

Scope

scope=ZohoRecruit.bulk.read
(and)
scope=ZohoRecruit.modules.{module_name}.{operation_type}

Possible module namesPossible operation types
​candidate, jobopening, client, interview, contact, custommoduleALL - Full access to the record
READ - Get bulk read job

Request JSON

AttributesData TypeMandatoryDescription
callback Show propertiesJSON ObjectNoA valid URL, which should allow the HTTP Post method. The Bulk Read Job's details are posted to this URL upon successful completion of the job or upon failure of the job. Sample - "callback" : { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }

Show Callback Properties

AttributesData TypeMandatoryDescription
urlString(URL)YesA valid URL, which should allow the HTTP POST method. The Bulk Read Job's details are posted to this URL upon successful completion of the job or upon failure of the job.
methodStringYesSpecifies the HTTP method of the callback url. Only the HTTP POST method is supported the allowed value 'post'.
query
Show properties		JSON ObjectYesPlease refer to the below table for information on a query JSON object.
file_typeStringYes, when you want to export the events as an ICS file.Specify the value for this key as "ics" to export all records in the Events module as an ICS file.

Show Query Properties

AttributesData TypeMandatoryDescription
moduleStringYesSpecifies the API Name of the module to be read. eg: Candidates, Contacts. Sample - "module" : "Candidates”. Specify the module name as "Events" if you want to export the records in the Events module as an ics file.
cvidStringYes, when you want to export records in a custom viewSpecifies the unique ID of the custom view whose records you want to export. You can obtain the cvid from the Custom View Metadata API.
selectfieldsArrayNoSpecifies the API Name of the fields to be fetched. eg: First_Name, Last_Name, Email, Owner.last_name. Sample - "selectfields" : ["First_Name", "Last_Name", "Email”, "Owner.last_name"]. Do not input this key when you want to export the records in the Events module as an ICS file.
pageIntegerNoThe default value for a page is 1. The page value '1' means that the first 200,000 records matching your query will get exported. If you want to fetch the records from the range 200,001 to 400,000 then you should mention the page as '2'.
criteria Show propertiesJSON ObjectNoTo filter the records to be exported. Ex: The API Name of a module or field, comparators used to add two or more criteria, a group to which the record/module/field belongs, etc.

Show criteria Properties

AttributesData TypeMandatoryDescription
api_nameStringYes, if group & group_operator are not specified.API name of a field to be compared. eg: First_Name, Last_Name, Owner.last_name etc,.
valueString or ArrayYes, if group & group_operator are not specified.Positive Integer values only
group_operatorStringYes, if api_name, comparator & value are not specified.Logical operators. Supported values - and, or.
groupArray (criteria JSON object)Yes, if api_name, comparator & value are not specified.An array of criteria objects.
comparator Show propertiesStringYes, if group & group_operator are not specified.Specifies any kind of comparator. eg: equal, greater_than. Refer to the table given below for more details.

Response Structure

AttributeData TypeDescription
statusStringSpecifies the status of the API call. Sample - "status": "success".
messageStringSpecifies the pre-defined comments for the job. Useful in case any errors occur. Sample - "message": "Added successfully."
details Show propertiesJSON ObjectPlease refer to the below table for information on the "details" JSON object.

Note

  • A maximum of two hundred thousand records can be exported in a single export job. i.e, "page" would be "1" and the records in the page would be "200,000". To know more about the Bulk API limits, go here.
  • The first 200,000 records matching the criteria are taken for export if the value of the "page" is "1".
  • To fetch data from parent modules, use the "."(dot) operator.
  • Use only API names of fields and modules in the input.
  • If the "selectfields" attribute in the query JSON is left empty, all the fields available for the corresponding base module are listed in the CSV file. In case you need only specific fields, specify the field API names for export.
  • It is mandatory to specify the cvid if you want to export records under a custom view.
  • Along with cvid, you can also specify additional criteria. These criteria will be appended with the existing criteria for the custom/standard view.

For ICS file type:

  • Exporting records in ICS format is supported only for the Events module.
  • You can export a maximum of 20,000 records from the Events module per batch.
  • The "selectfields" attribute is not supported when you want to export the events as an ICS file.
  • If you do not specify "file_type" as "ics", the records will be exported in the CSV format, by default.
  • If the value of more_records is "true" in the response of the Get Job Details API call, there are more records to be fetched.
  • For more info, refer to Limitations.

Sample Request

Copiedcurl "https://recruit.zoho.com/recruit/bulk/v2/read"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@inputData.json"

In the request, @inputData.json contains the sample input data.

Sample Response

Copied{
    "data": [{
        "status": "success",
        "code": "ADDED_SUCCESSFULLY",
        "message": "Added successfully.",
        "details": {
            "id": "17774000000749001",
            "operation": "read",
            "state": "ADDED",
            "created_by": {
                "id": "17774000000410003",
                "name": "Patricia Boyle"
            },
            "created_time": "2020-11-10T06:45:58+05:30"
        }
    }],
    "info": {}
}