The Contacts API is one of the most frequently used endpoints for automation. Whether you are syncing new sign-ups from your website or importing vendors from a procurement system, programmatically creating contacts ensures your ledger is always up to date without manual data entry.
At Kalki LLP, we specialize in "Clean-Data" integrations, ensuring that every contact created via API has the correct tax treatments, currency settings, and portal access from day one.
To create a new contact, send a POST request to your regional endpoint.
Endpoint: POST /contacts?organization_id={organization_id}
While Zoho only strictly requires the contact_name, a professional integration should include fiscal details.
| Parameter | Type | Description |
| contact_name | String | Required. Display name (Max 200 characters). |
| company_name | String | Legal company name. |
| contact_type | String | customer or vendor. |
| currency_id | Long | The ID of the contact's currency (e.g., INR, USD). |
| payment_terms | Int | Net terms (e.g., 15 for Net 15). |
| vat_treatment | String | Tax treatment (e.g., gst_registered, overseas). |
| gst_no | String | 15-digit GST identification number (for India). |
A standard request includes the contact's name, their primary address, and their tax settings.
{
"contact_name": "Kalki LLP Enterprises",
"company_name": "Kalki Solutions Pvt Ltd",
"contact_type": "customer",
"billing_address": {
"attention": "Accounts Dept",
"address": "123 Business Hub",
"city": "Gurugram",
"state": "Haryana",
"zip": "122001",
"country": "India"
},
"is_portal_enabled": true,
"language_code": "en"
}
Inside Zoho Creator or CRM, you can automate this using the zoho.books.createRecord task, which handles the headers and authentication for you.
// Prepare the Contact Data Map
contactData = Map();
contactData.put("contact_name", "Kalki LLP New Customer");
contactData.put("contact_type", "customer");
contactData.put("currency_id", "460000000000097"); // Use actual ID
// Call Zoho Books
response = zoho.books.createRecord("contacts", "10234695", contactData, "kalki_connection");
if(response.get("code") == 0)
{
newContactID = response.get("contact").get("contact_id");
info "Contact Created! ID: " + newContactID;
}
else
{
info "Error: " + response.get("message");
}
If your contact creation fails, check these common error codes:
| Error Code | Message | Fix for Kalki LLP Developers |
| 3000 | Duplicate Contact Name | A contact with this name already exists in your Zoho Books organization. |
| 9004 | Invalid Currency ID | The currency_id provided does not exist in your organization settings. |
| 1038 | JSON Not Well Formed | Check for trailing commas or missing quotes in your request body. |
| 57 | Unauthorized | Your Access Token has expired. See Step 4 of our OAuth guide. |
A single "Contact" (the company) can have multiple "Contact Persons" (the humans you talk to). You can include them in the initial creation by adding a contact_persons array to your JSON. This is vital for ensuring invoices are emailed to the correct individuals automatically.
Don't let manual entry slow down your sales cycle. Kalki LLP can help you bridge the gap between your CRM/Website and Zoho Books, ensuring your customer data is accurate, tax-compliant, and perfectly synced.