How to retrieve a single record in Zoho

Retrieving a single record in Zoho CRM via the API means targeting one specific entry by its unique record ID, returning only the data you need without pulling an entire list.

Why this matters

When building integrations or automations, fetching a full list of records just to read one is wasteful and slow. Pinpointing a record by ID keeps API calls lean, avoids hitting rate limits, and makes your Deluge or REST-based workflows far easier to maintain. This pattern is especially common when a trigger (such as a workflow or webhook) already supplies you with a record ID and you simply need to enrich or validate that record's data.

> Note: Beam Help is independent expert support for Zoho — we are not official Zoho support.

---

Step-by-step

Step 1. Obtain a valid OAuth access token for Zoho CRM.

Before any API call, your client must exchange its credentials for a bearer token. The token is passed in every request header as Authorization: Zoho-oauthtoken <your_token>. Without this, the CRM API will reject the request. ^[3]

Step 2. Identify the module and the record ID you want to retrieve.

Zoho CRM organises data into modules such as Leads, Contacts, Accounts, Deals, and so on. Every record inside a module has a unique numeric id (for example, 3652397000009851001). You must know both the module name and the record ID before making the call. ^[3]

Step 3. Construct the GET request to the single-record endpoint.

The Zoho CRM v8 API exposes individual records at:

GET https://www.zohoapis.com/crm/v8/{Module}/{record_id}

Replace {Module} with the API name of the module (e.g., Leads, Contacts) and {record_id} with the numeric ID from Step 2. A minimal curl example looks like this:

curl "https://www.zohoapis.com/crm/v8/Leads/3652397000009851001" \
  -X GET \
  -H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

^[3]

Step 4. Optionally limit the fields returned using the fields query parameter.

To reduce payload size, append ?fields= followed by a comma-separated list of API field names. For example, to retrieve only the last name and email address of a lead:

GET /crm/v8/Leads/3652397000009851001?fields=Last_Name,Email

This mirrors the same fields parameter used in list calls and keeps your response compact. ^[3]

Step 5. Parse the response.

A successful call returns a data array containing a single object. Pull the fields you need directly from that object. For example, in a JSON response you would access data[0].Last_Name or data[0].Email. The record's id is always present in the response regardless of which fields you requested. ^[3]

Step 6. Handle the record inside Deluge (if using Zoho CRM workflows or functions).

If you are calling the API from within a Deluge script rather than an external system, use the invokeurl task with the same endpoint and OAuth header. Store the parsed response in a map variable, then use .get("fieldapiname") to extract individual values — the same pattern used when working with other Zoho product APIs. ^[2]

---

Common pitfalls

• Wrong module API name. The module name in the URL must match the CRM API name exactly, including capitalisation (e.g., Leads not leads). A mismatch returns a 404 or an INVALID_MODULE error. ^[3]
• Expired or missing OAuth token. Tokens have a limited lifespan. If you receive a 401 INVALID_TOKEN response, refresh your access token before retrying. ^[3]
• Requesting a converted lead without the converted flag. When fetching leads that have already been converted, the standard endpoint may not return them unless you explicitly include ?converted=true in list-based calls. For single-record lookups, confirm the record still exists in the module you are querying. ^[3]
• Confusing record ID formats. IDs in Zoho CRM are long numeric strings. Passing a truncated or incorrectly typed ID will result in a record-not-found error. Always copy the ID programmatically rather than manually. ^[3]

---

What to check

• Confirm the response data array contains exactly one object — if it is empty, the record ID does not exist in that module or your token lacks the required scope.
• Verify field API names in the CRM module's field settings match what you passed in the fields parameter; display names and API names often differ.
• Check that your OAuth scope includes ZohoCRM.modules.READ (or the module-specific equivalent) so the token is authorised to read the target module's records. ^[3]