If you're building a Custom Module with custom fields in Zoho Books via the public API, for example a vendor or item alias table for e-invoice matching, there are two undocumented behaviours worth knowing before you hit them yourself, since both produce misleading errors that point you toward the wrong fix.

Issue 1: Lookup Custom Fields Need Both related_entity and related_list_name

When creating a custom field of data_type "lookup" via POST /booksv3/customfields, Zoho's own documented example body includes both related_entity (such as "contact") and related_list_name (such as "Related Invoices"). What the documentation doesn't state clearly is that both parameters are required together for the call to succeed.

The documentation also doesn't enumerate valid related_entity values for a lookup pointing to a custom module specifically; the published example only shows "contact". Through direct testing, both "item" and "vendor" have been confirmed to work as valid related_entity values for this purpose.

Issue 2: Custom Module Description Is Silently Capped at 150 Characters

When creating a Custom Module via POST /booksv3/settings/custommodules, the description field has an undocumented maximum length of 150 characters. Exceeding it returns error code 15, with no length limit stated anywhere on the Custom Modules API documentation page.

Practical Takeaway

Neither of these is a bug exactly; both are working as designed, just undocumented. If you're building against these two endpoints:

• Always send related_entity and related_list_name together on a lookup-type custom field, even though the doc's phrasing makes the second one look optional.
• Keep a Custom Module's description under 150 characters, and treat error code 15 as a likely length issue if you hit it unexpectedly.
• If you see error code 120128 on a lookup field creation call, check for a missing related_list_name before assuming your related_entity value itself is wrong.

The Wider Gap This Points To

Zoho has already demonstrated a strong pattern for exactly this class of problem elsewhere in its platform. Catalyst by Zoho ships an official, open-source Agent Skills repository, giving AI coding agents structured, accurate knowledge of Catalyst's SDKs and quirks, backed by a first-party Zoho MCP server that tools like Claude, Gemini, Cursor, and Copilot can connect to directly. Zoho Books and the wider finance suite (Invoice, Expense, Inventory) don't currently have an equivalent, so partners building AI-agent automation against these APIs are left discovering and patching gaps like the two above through direct trial and error against production data, rather than working from documentation that already accounts for them.