The List Contacts API allows you to retrieve a collection of all customers and vendors within a Zoho Books organization. Because businesses often have thousands of records, mastering the pagination and filtering parameters of this endpoint is essential for building high-performance integrations.
At Kalki LLP, we use these filtering techniques to help businesses generate custom reports and keep their external databases in sync with real-time financial data.
To fetch your contacts, send a GET request. By default, Zoho returns 200 records per page.
Endpoint: GET /contacts?organization_id={organization_id}
| Header Name | Value | Description |
Authorization | Zoho-oauthtoken {access_token} | Requires ZohoBooks.contacts.READ scope. |
To avoid downloading unnecessary data, use these parameters to narrow down your results:
| Parameter | Type | Description |
contact_name | String | Search for contacts by name (partial match). |
email | String | Search for a contact by their primary email address. |
status | String | Filter by status: active, inactive, or all. |
contact_type | String | Filter by customer or vendor. |
sort_column | String | Sort by contact_name, first_name, last_name, etc. |
page | Integer | The page number to retrieve (Default: 1). |
per_page | Integer | Number of records per page (Max 200). |
Example URL for Kalki LLP Developers:
GET /contacts?organization_id=12345&contact_type=customer&status=active&sort_column=contact_name
The response includes a contacts array and a page_context object to help you manage large datasets.
{
"code": 0,
"message": "success",
"contacts": [
{
"contact_id": "460000000026049",
"contact_name": "Kalki LLP Solutions",
"company_name": "Kalki Tech",
"contact_type": "customer",
"status": "active",
"email": "info@kalkillp.com",
"outstanding_receivable_amount": 1500.00,
"currency_code": "INR"
}
],
"page_context": {
"page": 1,
"per_page": 200,
"has_more_page": true
}
}
When working within Zoho, you can handle the list and loop through results using this pattern:
// Parameters to filter only active vendors
params = Map();
params.put("contact_type", "vendor");
params.put("status", "active");
response = zoho.books.getRecords("Contacts", "123456789", params, "kalki_connection");
if(response.get("code") == 0)
{
contactsList = response.get("contacts");
for each contact in contactsList
{
info "Vendor: " + contact.get("contact_name") + " | Email: " + contact.get("email");
}
// Logic to check for more data
if(response.get("page_context").get("has_more_page") == true)
{
info "Note: More vendors exist. Fetch page 2 if needed.";
}
}
| Error Code | Meaning | Fix |
| 57 | Unauthorized | Your Access Token has expired. Refresh using Step 4 of the OAuth guide. |
| 45 | Rate Limit | You've exceeded the 100 requests per minute limit. |
| 2 | Invalid ID | The organization_id is missing or incorrect. |
| Empty List | No Results | Your filters (e.g., email) matched zero records. Verify the search string. |
Including this guide on kalkillp.com targets developers looking for specific queries like "Zoho Books search contact by email" or "Zoho Books API list active vendors." By demonstrating how to use page_context, you show that your team understands how to handle enterprise-level data volume.
Stop fetching your entire database every time you need a single contact. Kalki LLP can help you implement advanced server-side search logic to make your integrations lightning-fast.