Get the Status of the Bulk Read Job

Purpose

To get the details of a bulk read job performed previously.

Request Details

Request URL

{api-domain}/crm/bulk/{version}/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/v6/read/3652397000000646004"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample 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/v6/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/v6/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.

Note

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/v6/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/v6/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"
        }
    ]
}