Get Records

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.

Purpose

To get the list of available records from a module, or to get the details of a specific record with its unique record ID.

Endpoints

GET /{module_api_name}
GET /{module_api_name}/{record_id}

{module_api_name} : API name of the module whose records you want to retrieve
{record_id} : The unique ID of the record you want to fetch.

Request Details

Request URL

{api-domain}/crm/{version}/{module_api_name}

To get specific record:
{api-domain}/crm/{version}/{module_api_name}/{record_id}

Supported modules

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

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 get the module API name from the api_name key in the Modules API's response.

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, services.

Possible operation types

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

Parameters

fieldsstring, mandatory when fetching all records
Specify the API names of the fields you want to retrieve when fetching the records. Note that you can include a maximum of 50 field API names in this parameter. Use the GET - Fields Metadata API to retrieve the list of available fields in a module.
Possible values: Multiple field API names, in a comma separated format. For example: Last_Name, Email.
Note: The full_name field contains the concatenated values of the First Name and Last Name fields.
This is a read-only field available only in the Leads, Contacts, and Users modules.
cvidlong
Specify the custom view ID 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 the response of 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
per_pageinteger
Specify how many records to return per page. The default and the maximum possible value is 200.
Possible values: Positive integer values only.
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.
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.
sort_orderstring
To sort the available list of records in either ascending or descending order, based on the value of "sort_by" parameter.
Possible values:
- desc - Displays records in descending order. This is the default value.
- asc - Displays records in ascending order.
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 parameter with the "cvid" parameter.
convertedstring
To get the list of converted records. Default value is false.
Possible values:
- false - get only non-converted records.
- true - get only converted records.
- both - get all records.
territory_idlong
Specify the territory ID to get the list of records that belongs to a specific territory. You can get the territory IDs using Get Territories API.
Possible value: {territory_id}.
include_childboolean
To include records from the child territories. Default value is false.
Possible values:
- false - do not include child territory records.
- true - include child territory records.

Note

"sort_order" applies to given "sort_by" field. If "sort_by" parameter 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).
Pagination
- 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.
Use the key $approval_state in the fields param to retrieve the approval status of the record.
The keys Converted__s and Converted_Date_Time represent whether the record is converted, and the date and time at which it was converted, respectively.
The fields Enrich_Status__s and Last_Enriched_Time__s are added for the Data Enrichment module.
You can get the values of subform records, 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 subforms, 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.
Only while fetching a specific record from one of the inventory modules, the response will contain 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)
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.
In the response of the Get Records API, rich text fields are truncated to display only the first 500 characters. Use the Rich Text Fields API to retrieve the complete content of rich text fields.

Sample Request: First API Call

Copiedcurl "https://www.zohoapis.com/crm/v8/Leads?fields=Last_Name,Email,Record_Status__s,Converted__s,Converted_Date_Time&converted=true&per_page=5"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Response to the First API Call

Copied{
    "data": [
        {
            "Converted_Date_Time": "2022-11-21T15:12:13+05:30",
            "Email": null,
            "Last_Name": "test8000",
            "id": "3652397000009851001",
            "Record_Status__s": "Available",
            "Converted__s": true
        },
        {
            "Converted_Date_Time": "2022-11-21T15:12:13+05:30",
            "Email": null,
            "Last_Name": "test7000",
            "id": "3652397000009850001",
            "Record_Status__s": "Available",
            "Converted__s": true
        },
        {
            "Converted_Date_Time": "2022-11-21T11:34:37+05:30",
            "Email": null,
            "Last_Name": "test6000",
            "id": "3652397000009843012",
            "Record_Status__s": "Available",
            "Converted__s": true
        },
        {
            "Converted_Date_Time": "2022-11-21T11:34:36+05:30",
            "Email": null,
            "Last_Name": "test3000",
            "id": "3652397000009843001",
            "Record_Status__s": "Available",
            "Converted__s": true
        },
        {
            "Converted_Date_Time": "2022-11-21T22:47:16+05:30",
            "Email": null,
            "Last_Name": "test2000",
            "id": "3652397000009836003",
            "Record_Status__s": "Available",
            "Converted__s": true
        }
    ],
    "info": {
        "call": false,
        "per_page": 5,
        "next_page_token": "c8582xx9e7c7",
        "count": 5,
        "sort_by": "id",
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": "2022-11-11T15:08:14+05:30",
        "sort_order": "desc",
        "email": false,
        "more_records": true
    }
}

Possible Errors

INVALID_MODULEHTTP 400
The module name given is 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/v8/Leads?fields=Last_Name,Email,Converted__s,Converted_Date_Time&converted=true&per_page=5&page_token=c85829xxx5a049e7c7"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Response to the Second API Call

Copied{
    "data": [
        {
            "Converted_Date_Time": "2022-11-11T15:12:13+05:30",
            "Email": null,
            "Last_Name": "test8000",
            "id": "3652397000009851001",
            "Converted__s": true
        },
        {
            "Converted_Date_Time": "2022-11-21T15:12:13+05:30",
            "Email": null,
            "Last_Name": "test7000",
            "id": "3652397000009850001",
            "Converted__s": true
        },
        {
            "Converted_Date_Time": "2022-11-21T11:34:37+05:30",
            "Email": null,
            "Last_Name": "test6000",
            "id": "3652397000009843012",
            "Converted__s": true
        },
        {
            "Converted_Date_Time": "2022-11-21T11:34:36+05:30",
            "Email": null,
            "Last_Name": "test3000",
            "id": "3652397000009843001",
            "Converted__s": true
        },
        {
            "Converted_Date_Time": "2022-11-21T22:47:16+05:30",
            "Email": null,
            "Last_Name": "test2000",
            "id": "3652397000009836003",
            "Converted__s": true
        }
    ],
    "info": {
        "call": false,
        "per_page": 5,
        "next_page_token": "3040xxxx9d467",
        "count": 5,
        "sort_by": "id",
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": "2022-11-11T15:10:23+05:30",
        "sort_order": "desc",
        "email": false,
        "more_records": true
    }
}

Sample Response for Fetching a Specific Record

Copied{
    "data": [
        {
            "Company": "abc",
            "Owner": {
                "name": "Patricia Boyle",
                "id": "554023000000235011",
                "email": "p.boyle@abc.com"
            },
            "Email": "j.smith@abc.com",
            "Full_Name": "Jason Smith",
            "First_Name": "Jason",
            .
            .
            .
            "Languages_Known": [ //Custom Subform
                {
                    "Proficiency": "Professional",
                    "Modified_Time": "2023-06-23T23:47:59-11:00",
                    "Language": [
                        "English"
                    ],
                    "Layout": {
                        "name": "Standard",
                        "id": "554023000000885006"
                    },
                    "$in_merge": false,
                    "$field_states": null,
                    "Created_Time": "2023-06-23T23:47:59-11:00",
                    "Parent_Id": {
                        "name": "Steven",
                        "id": "554023000002750020"
                    },
                    "id": "554023000003129007",
                    "$zia_visions": null
                }
            ],...
            "$has_more": {
                "Associated_Deal": false, //Custom multi-select lookup
                "Languages_Known": false // Custom Subform
            }
        }
    ]
}