The List Contacts API allows you to retrieve a collection of all customers and vendors within a Zoho Books organization. Because a business can have thousands of contacts, mastering the pagination and filtering parameters of this endpoint is essential for building fast, efficient integrations.
At Kalki LLP, we use these filtering techniques to help businesses generate custom reports and keep their external dashboards 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 results by contact_name, first_name, last_name, etc. |
page | Integer | The page number to retrieve (e.g., 1, 2). |
per_page | Integer | Number of records per page (Max 200). |
Example Search URL:
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 pagination.
{
"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": 500.00,
"currency_code": "INR"
}
],
"page_context": {
"page": 1,
"per_page": 200,
"has_more_page": true
}
}
When dealing with more than 200 contacts, you need a script that understands pagination. Here is how we handle it:
// Fetch the first page of active customers
params = Map();
params.put("contact_type", "customer");
params.put("status", "active");
params.put("page", 1);
response = zoho.books.getRecords("Contacts", "123456789", params, "kalki_connection");
if(response.get("code") == 0)
{
contactsList = response.get("contacts");
for each contact in contactsList
{
info "Customer: " + contact.get("contact_name") + " | Balance: " + contact.get("outstanding_receivable_amount");
}
// Check if there are more pages
if(response.get("page_context").get("has_more_page") == true)
{
info "Note: More customers available on Page 2.";
}
}
| Error Code | Meaning | Fix for Kalki LLP Developers |
| 57 | Unauthorized | Your Access Token has expired. Refresh using Step 4 of our OAuth guide. |
| 45 | Rate Limit Exceeded | You've called this endpoint too many times in one minute. Implement a delay. |
| 2 | Invalid ID | The organization_id is missing or incorrect. |
| Empty List | No Results | Your filters (e.g., email or status) matched zero records. Verify the search criteria. |
Adding this guide to kalkillp.com targets developers looking for "Zoho Books search contact by email" or "List active vendors Zoho API." By showing them how to use parameters like contact_type, you prove that your team understands the nuances of the Zoho database, making you the preferred partner for complex migration and sync projects.
Stop fetching the entire database every time you need a single contact. Kalki LLP can help you implement advanced filtering and server-side search logic to make your integrations lightning-fast.