Get Records API

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.

Endpoints

GET /{module_api_name}

GET /{module_api_name}/{record_id}

Request Details

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}

To get specific record:
https://www.zohoapis.com/crm/v2/{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, Activities, and custom modules (Refer to the following section).

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: Use this header to get the list of recently modified records. Example: 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, activities, and custom

Note: The module name for all the custom modules will be custom.

Possible operation types

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

Parameters

fieldsstring, optional
To retrieve specific field values.
Possible values: Comma separated field API names. Example: Last_Name,Email
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
sort_orderstring, optional
To sort the list of records in either ascending or descending order.
Possible values:asc - ascending order; desc - descending order
sort_bystring, optional
Specify the API name of the field based on which the records must be sorted. The default value is id. If you provide invalid values, default sorting will take place.
Possible values: Field API names. Example: Email
convertedstring, optional
To retrieve 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
approvedstring, optional
To retrieve the list of approved records. Default value is true.
Possible values:true - get only approved records; false - get only records which are not approved; both - get all records
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.
pageinteger, optional
To get the list of records from the respective pages. Default value for page is 1.
Possible values: Positive Integer values only.
per_pageinteger, optional
To get the list of records available per page. The default and the maximum possible value is 200.
Possible values: Positive Integer values only.
cvidlong, optional
To get the list of records in a custom view.
Possible values: {custom_view_id} which you can get using Custom View Metadata API.
territory_idstring, optional
To get the list of records in a territory.
Possible values: {territory_id} which you can get using Territory API.
include_childboolean, optional
To include records from the child territories. Default is false.
Possible values:true - include child territory records; false -does not include child territory records

Note

The sort_order parameter applies to given sort_by parameter value.
If sort_by field is not provided, then it applies to the system-defined field.
The page and per_page parameter is used to fetch records according to their position in the CRM. Let's assume that the user has to fetch 400 records. The maximum number of records that one can get for an API call is 200. So, for records above the 200th position, they cannot be fetched. By using the page (1 and 2) and per_page (200) parameter, the user can fetch all 400 records using 2 API calls.
Refer to Response Structure for more details about the JSON keys, values, and their descriptions.
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 information in a module.
To get the list of territories enabled for your organization, refer to 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.
To know more about the field types and limits, refer to Insert Records API.

Response JSON Keys

OwnerJSON object
Represents the name, ID, and email ID of the record owner.
$currency_symbolstring
Represents the symbol of the currency of the organization. For instance, '₹'.
$process_flowboolean
Represents if the record is a part of review process.
true: The current record is a part of the review process.
false: The current record is not a part of the review process. This is the default value.
Exchange_Ratedouble
Represents the exchange rate set for the organization.
Currencystring
Represents the currency of the organization.
$approvedboolean
Represents if the current record is approved.
true: The current record is approved. This is the default value.
false: The current record is yet to be approved.
$approvalJSON object
Represents the details of the approval process.
Created_Timestring
Represents the date and time at which the record was created.
Modified_Timestring
Represents the date and time at which the record was last modified.
$editableboolean
Represents if the user can edit records in the current module.
true: The user can edit records in the current module. This is the default value.
false: The user does not have permission to edit records in the current module.
Created_ByJSON object
Represents the name, ID, and email of the user who created the current record.
Modified_ByJSON object
Represents the name, ID, and email of the user who last modified the record.
$orchestrationboolean
Represents if the current record is a part of orchestration.

Note

The keys listed above are common for all the modules. Along with the above keys, module-specific keys will also be retrieved in the response.
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

Curl Java PHP Csharp Python Node JS Ruby JavaScript Deluge

Copiedcurl "https://www.zohoapis.com/crm/v2/Leads/1306462000000888026"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Copiedresponse = invokeurl
[
	url: "https://www.zohoapis.com/crm/v2/Accounts"
	type: GET
	connection:"crm_oauth_connection"
];
info response;

Sample Response

Copied{
    "data": [
        {
            "Owner": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "Company": "SolutionsTech",
            "Email": null,
            "$currency_symbol": "$",
            "$field_states": null,
            "Last_Activity_Time": "2022-02-03T10:55:15+05:30",
            "Industry": null,
            "$state": "save",
            "Unsubscribed_Mode": null,
            "$converted": false,
            "$process_flow": false,
            "Test": null,
            "Street": null,
            "Data_Processing_Basis_Details": null,
            "Zip_Code": null,
            "id": "1306462000000888026",
            "Data_Source": "API",
            "$approved": true,
            "$approval": {
                "delegate": false,
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "$data_source_details": {},
            "Created_Time": "2022-02-02T17:09:49+05:30",
            "$editable": true,
            "City": null,
            "No_of_Employees": null,
            "Related": null,
            "State": null,
            "Country": null,
            "Created_By": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "Annual_Revenue": null,
            "Secondary_Email": null,
            "Description": null,
            "Rating": null,
            "$review_process": {
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "Website": null,
            "Twitter": null,
            "Information": null,
            "$canvas_id": null,
            "Salutation": null,
            "Marital_Status_1": null,
            "Birthday_1": null,
            "First_Name": null,
            "Full_Name": "Sam",
            "Lead_Status": null,
            "Record_Image": null,
            "Modified_By": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "$review": null,
            "Skype_ID": null,
            "Phone": null,
            "Lead_Class": "Class S",
            "Email_Opt_Out": false,
            "Designation": null,
            "Modified_Time": "2022-02-03T10:55:15+05:30",
            "$converted_detail": {},
            "Unsubscribed_Time": null,
            "Referred_By": null,
            "Mobile": null,
            "$orchestration": false,
            "$stop_processing": false,
            "Last_Name": "Sam",
            "$in_merge": false,
            "Lead_Source": null,
            "Tag": [],
            "Fax": null,
            "$approval_state": "approved"
        }
    ]
}

Converted Records

To retrieve the converted records, the converted parameter should be true or both. The converted_detail key in the response renders the conversion details which includes the deal (deal id), convert_date, contact (converted contact id), converted_by and account (account id). Please refer to the sample response for more details.

Possible Errors

INVALID_MODULEHTTP 400
The module name given seems to be invalid
Resolution: You have specified an invalid module name or there is no tab permission, or the module could have been removed from the available modules. Specify a valid module API name.
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 been supported). Specify a valid module API name.
INVALID_MODULEHTTP 400
Territory is not supported for the given module
Resolution: The module you have specified is not territory-supported. Territory is supported only for the modules Deals, Contacts, and Accounts.
NOT_SUPPORTEDHTTP 403
This API is supported only for admin users
Resolution: Only admin users can fetch records from the Notes module.
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.modules.{module_name}.READ scope. 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 data. 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 records data
Resolution: The user does not have the permission to retrieve modules data. Contact your system administrator.
PATTERN_NOT_MATCHEDHTTP 400
Please check whether the input values are correct
Resolution: The value specified for one of the parameters is incorrect. Refer to parameters section above and specify valid parameter values.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/Leads?converted=true&approved=true"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "data": [
        {
            "Owner": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "Company": null,
            "Email": "j.smith@xyz.com",
            "$currency_symbol": "$",
            "$field_states": null,
            "Last_Activity_Time": "2021-10-05T14:37:26+05:30",
            "Industry": "Service Provider",
            "$state": "save",
            "Unsubscribed_Mode": null,
            "$converted": true,
            "$process_flow": false,
            "Test": null,
            "Street": "37275 St Rt 17m M",
            "Data_Processing_Basis_Details": null,
            "Zip_Code": "11953",
            "id": "1306462000000391002",
            "Data_Source": "API",
            "$approved": true,
            "$approval": {
                "delegate": false,
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "$data_source_details": {},
            "Created_Time": "2021-08-24T14:52:07+05:30",
            "$editable": true,
            "City": "Middle Island",
            "No_of_Employees": null,
            "State": "NY",
            "Country": "United States",
            "Created_By": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "Annual_Revenue": 850000,
            "Secondary_Email": null,
            "Description": null,
            "Rating": null,
            "$review_process": {
                "approve": false,
                "reject": false,
                "resubmit": false
            },
            "Website": "http://www.rangoniofflorence.com",
            "Twitter": "christophermaclead_sample",
            "Information": null,
            "Salutation": "Mr.",
            "Marital_Status_1": null,
            "Birthday_1": null,
            "First_Name": "Jim",
            "Full_Name": "Mr. Jim Smith",
            "Lead_Status": "Lost Lead",
            "Record_Image": "02b9e93996ad174d0c685bd56b94e9d760497ba52e17145a73c18292ae60c1d81915036312ccaf1faaf8c8168eeff1cf427c96c3020bcd3da31280be451e09164c5ce0a2e1ff5d13109c3d1eac14bfdd",
            "Modified_By": {
                "name": "Patricia Boyle",
                "id": "1306462000000374001",
                "email": "p.boyle@abc.com"
            },
            "$review": null,
            "Skype_ID": "christopher-maclead",
            "Phone": "555-555-5555",
            "Lead_Class": null,
            "Email_Opt_Out": false,
            "Designation": "VP Accounting",
            "Modified_Time": "2021-10-05T14:37:26+05:30",
            "$converted_detail": {
                "deal": "1306462000000519017",
                "convert_date": "2021-10-05T20:07:26+05:30",
                "contact": "1306462000000396035",
                "converted_by": "1306462000000374001",
                "account": "1306462000000497010"
            },
            "Unsubscribed_Time": null,
            "Referred_By": null,
            "Mobile": "9400000001",
            "$orchestration": false,
            "$stop_processing": false,
            "Last_Name": "Maclead (Sample)",
            "$in_merge": false,
            "Lead_Source": "Cold Call",
            "Tag": [],
            "Fax": "1234123415",
            "$approval_state": "approved"
        }
    ],
    "info": {
        "call": false,
        "per_page": 200,
        "count": 1,
        "page": 1,
        "email": false,
        "more_records": false
    }
}

Get Records API

Purpose

Endpoints

Request Details

Request URL

Supported modules

Custom modules

Header

Scope

Possible module names

Possible operation types

Parameters

Response JSON Keys

Sample Request

Sample Response

Converted Records

Possible Errors

Sample Request

Sample Response

Further Reading