Get Records

Purpose

A record is an entity which stores all the combined information of a particular contact or company, which is acquired from various sources. The information may be acquired from a web-form, social media services, advertisements etc. The records API allows the user to get, create, update, delete, or search records.

Endpoints

GET /{module_api_name}

GET /{module_api_name}/{record_id}

Request Details

Request URL

{api-domain}/crm/{version}/{module_api_name}
To get specific record:
https://www.zohoapis.com/crm/{version}/{module_api_name}/{record_id}

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Meetings, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Custom, Appointments, Appointments Rescheduled History, and Services.

Custom Modules

For custom modules, use their respective API names in the request URL. You can obtain the API name from Setup -> Developer Hub -> APIs & SDKs -> API Names. You can also use the respective custom module's api_name key in the Modules API's response to get the API name of the custom module.

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

If-Modified-Since: 2019-07-25T15:26:49+05:30

Scope

scope=ZohoCRM.modules.ALL
(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, custom, appointments, appointments_rescheduled_history, and services.

Possible operation types

ALL - Full access to the record
READ - Get records from the module

Parameters

fieldsstring, mandatory when fetching all records
To list all the module records with respect to fields. Note that you can include a maximum of 50 field API names in this parameter.
Possible values: Multiple field API names, comma separated. For example: Last_Name,Email.
cvidlong
To get the list of records based on custom views. Note that you cannot use this param with the "sort_by" param.You can get custom view id from Custom View Meta API
Possible values: {custom_view_id}.
idsstring, optional
To retrieve specific records based on their unique ID.
Possible values: Valid unique IDs of records. Example: 4150868000001944196
Multiple IDs can be comma separated. Example:4150868000001944196,4150868000001944187,4150868000001944134
pageinteger
To get the list of records from the respective pages. The default value is 1. Note that you cannot use this param with the "page_token" param.
Possible values: Positive integer values only.
per_pageinteger
To get the list of records available per page. The default and the maximum possible value is 200.
Possible values: Positive integer values only.
page_tokenstring, mandatory to fetch more than 2000 records by pagination
You can use the "page" param to fetch up to 2000 records without "page_token". To fetch more than 2000 records, you must include the "page_token" param in the request. This param takes the value from the key "next_page_token" in the response of the first Get Records call. Note that this token value is user-specific. If you use another user's token, the system throws an error.
Note that you cannot use this param with the "page" param.
approval_statestring, optional
To retrieve the list of records based on various approval stages.
- approved : To list the approved records.
- approval_process_pending : To list all the records whose approval process is pending.
- approval_process_rejected : To list all the records whose approval was rejected.
- review_process_pending : To list all the records whose review process is pending.
- review_process_rejected : To list all the records whose review process is rejected.
- webform_unapproved : To list all the unapproved records created via webforms.
- webform_invalid : To list all the invalid records created through the webform.
- webform_invalid_approval : To list all the invalid records created through the webform that are waiting for approval.
- webform_double_optin : To list all records created via webforms with Double Opt-in enabled. Check here for more details.
- merge_pending : To list all the records whose merge process is pending.
- zia_vision_pending : To list all the records whose Zia Vision process is pending.
- zia_vision_validation : To list all the records whose Zia Vision process is in a validation state.
- zia_vision_rejected : To list all the records whose Zia Vision process is rejected.
sort_orderstring
To sort the available list of records in either ascending or descending order.
Possible values: asc - ascending order, desc - descending order. The default value is 'desc'.
sort_bystring
To sort the records based on the fields id, Created_Time, and Modified_Time. The default value is 'id'. Note that you cannot use this param with the "cvid" param.
convertedstring
To get the list of converted records. Default value is false.
Possible values: true - get only converted records, false - get only non-converted records, both - get all records.
territory_idlong
To get the list of records based on the territory.
Possible values: {territory_id}.
include_childboolean
To include records from the child territories.Default value is false.
Possible values: true - includes child territory records, false - does not include child territory records.

Note

sort_order applies to given sort_by field.
If sort_by field is not provided, then it applies to the system-defined field.
If your requirement is to fetch under 2000 records, use the "page" and "per_page" parameters (page=1 to 10, per_page=200).
If you want to paginate for more than 2000 records, use the "page_token" parameter you receive in the first response. You will have to pass the page token received from the response with param page=10 to get records from 2001 to 2200. If there are more records, the API responses, will have "next_page_token" and "previous_page_token" for easy pagination.
Using the page tokens from the consecutive requests, you can navigate and fetch up to 100,000 records.
The key "page_token_expiry" contains the time when next_page_token and previous_page_token expires.
Note that in both the above scenarios, the maximum records per request will be only 200.
While retrieving multiple records, subform records are not retrieved. Only the records count in a subform is retrieved.
To get the record details in a subform, you need to fetch the specific record's information in a module.
Only while fetching a specific record from one of the inventory modules, the response will contain one of the following subforms:
- Quoted_Items (for a Quote)
- Invoiced_Items (for an Invoice)
- Ordered_Items (for a Sales Order)
- Purchased_Items (for a Purchase Order)
You can get the values of multi-select lookup fields and multi-user lookup fields in the response only when a specific record is fetched.
The $has_more JSON object in the response renders the API names of the multi-select lookup fields and multi-user lookup fields in the module with boolean values to indicate whether or not there are more records in these fields in the module. This key is rendered in the response only when you fetch a specific record.
Use the $event_cancelled key in the fields param to retrieve the cancellation status of the Meeting. The $event_cancelled key in the response represents the cancellation status of the Meeting.
To get the list of territories enabled for your organization, refer to the Territories API.
Territory is supported only for the modules Deals, Contacts, and Accounts.
Only admin users can fetch the records from the Notes module. The system throws an error when non-admin users try to fetch the records from the Notes module.
The value of the fields with sensitive health data will be retrieved only when Restrict Data access through API option in the compliance settings is disabled. If the option is enabled, the value will be null. Refer to HIPAA compliance for more details.

Sample Request: First API Call

Copiedcurl "https://www.zohoapis.com/crm/v3/Leads?fields=Last_Name,Email&per_page=3"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Response to the First API Call

Copied{
    "data": [
        {
            "Email": "p.boyle@abc.com",
            "Last_Name": “Boyle”,
            "id": "3652397000006077001"
        },
        {
            "Email": “lead@crm.com”,
            "Last_Name": “CRM lead",
            "id": "3652397000006067001"
        },
        {
            "Email": "brian@villa.com",
            "Last_Name": "Dolan",
            "id": "3652397000006064047"
        }
    ],
    "info": {
        "call": false,
        "per_page": 3,
        "next_page_token": "187d2xxxxxxc50119e",
        "count": 3,
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": "2022-03-13T16:07:26+05:30",
        "email": false,
        "more_records": true
    }
}

Possible Errors

INVALID_MODULEHTTP 400
The module name given seems to be invalid.
Resolution: Specify a valid module API name. Refer to possible modules section above.
INVALID_MODULEHTTP 400
The given module is not supported in API.
Resolution: The modules such as Documents and Projects are not supported in the current API. (This error will not be shown, once these modules are supported). Specify a valid module API name. Refer to possible modules section above.
INVALID_MODULEHTTP 400
Territory is not supported for the given module.
Resolution: The given module is not territory-supported. Territory is supported only for the modules Deals, Contacts, and Accounts.
TOKEN_BOUND_DATA_MISMATCHHTTP 400
The page_token given seems to be invalid or input param is added, altered, or deleted.
Resolution: The page_token is bound to the parameters used in the request. Do not change the parameters and use the old page token.
INVALID_DATAHTTP 400
You have used unsupported fields in the "cvid" param.
Resolution: The "details" key in the response gives the supported fields you can use in the cvid param. Filter only by those fields.
REQUIRED_PARAM_MISSINGHTTP 400
One of the expected parameters is missing.
Resolution: The "details" key in the response gives the missing param in the request. Ensure that you include the params marked "mandatory" in the "Parameters" section.
LIMIT_EXCEEDEDHTTP 400
Fields limit exceeded.
Resolution: You can only include a maximum of 50 field API names in the "fields" param.
INVALID_DATAHTTP 400
The token given seems to be invalid. You have used an invalid page_token or the one generated by another user.
Resolution: page_token is user-specific. Use only the ones that are generated for you.
EXPIRED_VALUEHTTP 400
The token given has expired.
Resolution: page_token is valid only for 24 hours from the time it was generated.
DISCRETE_PAGINATION_LIMIT_EXCEEDEDHTTP 400
You can only get the first 2000 records without using page_token param.
Resolution: If you want to fetch more than 2000 records, you must use the "page_token" param.
AMBIGUITY_DURING_PROCESSINGHTTP 400
You cannot use both cvid and sort_by, and page and page_token
Resolution: You cannot sort the records in a custom view. Use either "cvid" or "sort_by" param in the request. Similarly, use either "page" or "page_token" in the request.
PAGINATION_LIMIT_EXCEEDEDHTTP 400
You can only get up to first 100000 records using page_token param.
Resolution: You can fetch a maximum of 100,000 records using the page_token param in the get records API.
NO_PERMISSIONHTTP 403
Permission denied to read records
Resolution: The user does not have permission to read records. Contact your system administrator.
NOT_SUPPORTEDHTTP 403
This API is supported only for admin users.
Resolution: Only admin users can fetch records from the Notes module.

Sample Request: Second API Call using "page_token"

Copiedcurl "https://www.zohoapis.com/crm/v3/Leads&fields=Last_Name,Email&per_page=3&page_token=187d2aa853ce291xxxxbc50119e"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Response to the Second API Call

Copied{
    "data": [
        {
            "Email": "p.daly2@zylker.com",
            "Last_Name": "Daly2",
            "id": "3652397000006064046"
        },
        {
            "Email": "brian1@villa.com",
            "Last_Name": "Dolan1",
            "id": "3652397000006064035"
        },
        {
            "Email": "p.daly1@zylker.com",
            "Last_Name": "Daly1",
            "id": "3652397000006064023"
        }
    ],
    "info": {
        "call": false,
        "per_page": 3,
        "next_page_token": "be95597xxxxxf19cf786ed1",
        "count": 3,
        "page": 2,
        "previous_page_token": "efcfe6dexxxx7e86547",
        "page_token_expiry": "2022-03-14T16:11:50+05:30",
        "email": false,
        "more_records": true
    }
}