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.

To retrieve the records that match your search criteria.

Request Details

Request URL

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

Supported modules

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

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, and activities.

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.

  • cvidinteger

    To get the list of records based on custom views. Note that you cannot use this param with the "sort_by" param.
    Possible values: {custom_view_id}.

  • pageinteger

    To get the list of records from the respective pages. 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_tokeninteger, 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.
    Possible values: asc - ascending order, desc - descending order.

  • sort_bystring

    To sort the records based on the fields id, Created_Time, and Modified_Time. Note that you cannot use this param with the "cvid" param.
    Possible values: Field API name.

  • 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_idinteger

    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. Using this next page token in the consecutive requests, you can navigate and fetch up to 100,000 records.
    Note that for this case, you can use page_token from page=2 itself, instead of page and per_page parameters. If there are more records, the API responses, will have "next_page_token" and "previous_page_token" for easy pagination.

  • 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.

  • 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)

  • The $has_more JSON object in the response renders the API names of the multi-select 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.

  • 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
    }
}