GST Number Verification in Zoho Books

Zoho Books will tell you that a GSTIN is shaped correctly. It will not tell you that the registration exists, that it is still Active, or that the legal name on it matches the contact you are about to invoice. Those are different questions, and the gap between them is where cancelled suppliers and mistyped numbers quietly live in a contact list.

Closing it takes a Deluge custom function and about twenty minutes. Here are the three routes, in increasing order of effort, and the one most teams should pick.

What Zoho Books validates on its own

Rows three to seven are the ones that cost money when they are wrong. A structurally valid GSTIN belonging to a cancelled registration passes every check Zoho makes and still puts your input tax credit at risk — see input tax credit rules.

Three routes to real verification

• Route 1 — manual, at the GST portal. Fine for a handful of contacts a month. Stops working the moment volume or turnover on your finance team makes it somebody's forgotten job.
• Route 2 — a Deluge custom function. Verification happens inside Zoho at the moment the contact is created or edited, and the result is written to custom fields on the record. This is the right answer for most teams and is described below.
• Route 3 — verify outside Zoho and write back through the Zoho Books API. Better when verification is already part of a larger pipeline, or when you want scheduled monitoring rather than event-driven checks.

Route 2: a Deluge custom function

Create four custom fields on the Contacts module first — cf_gst_status, cf_gst_legal_name, cf_gst_verified_at and cf_gst_einvoice — then attach a function to contact creation and edit.

gstin = contact.get("gst_no");

if(gstin != null && gstin.length() == 15)
{
    response = invokeurl
    [
        url: "https://gstinapi.com/api/get-taxpayer-info/" + gstin
        type: GET
        headers: {"x-api-key": "YOUR_API_KEY"}
    ];

    taxpayer = response.get("taxpayer_data");

    if(taxpayer != null)
    {
        update = Map();
        update.put("cf_gst_status", taxpayer.get("status"));
        update.put("cf_gst_legal_name", taxpayer.get("name"));
        update.put("cf_gst_einvoice", taxpayer.get("einvoiceStatus"));
        update.put("cf_gst_verified_at", zoho.currentdate.toString("yyyy-MM-dd"));

        zoho.books.updateRecord("Contacts", ORG_ID, contact.get("contact_id"), update);
    }
}

Three things that make this production-grade rather than a demo:

• Guard the call. The length check above is the minimum; a full format and mod-36 checksum check is better and costs nothing — see GSTIN format explained. Every typo caught locally is a credit you do not spend.
• Always write the timestamp, even when nothing else changed. A contact with a status and no date is indistinguishable from one verified in 2023.
• Handle the failure path. If the response has no taxpayer_data, write a distinct status such as UNVERIFIED rather than leaving the field blank — blank reads as "not checked yet", which is a different and much less alarming state than "we checked and could not confirm it".

Route 3: verify outside Zoho and write back

When verification belongs to a wider pipeline — a nightly job, an existing service, or a monitoring schedule rather than a create event — invert the flow: pull contacts from the Zoho Books API, verify them in your own code, and push results back into the same custom fields.

This is also the route to take for ongoing monitoring rather than one-time checks, since a create-time function never fires again for a contact that was fine at creation and was cancelled last month. The design for that is in automated daily vendor GSTIN monitoring, and working code in Python or Node.js. If you would rather not write code at all, Zapier and Power Automate both connect the two ends.

Cleaning up the contacts you already have

A create-time function protects the future. It does nothing about the contact list you already have, which is where the problems currently are.

1. Export contacts to CSV from Zoho Books, keeping contact ID and GSTIN.
2. Deduplicate and format-filter locally — free, and it removes the blanks and the PANs pasted into the GST column.
3. Run the batch through verification. See bulk verification from a CSV.
4. Triage the output: cancelled registrations first, then suspended, then legal-name mismatches, then contacts where nothing could be found at all.
5. Re-import or update the custom fields, and route the exceptions to whoever owns each relationship before the next payment run.

Pitfalls specific to Zoho Books

1. Trusting the built-in warning. It is a pattern check. It has never once contacted the GST systems.
2. Verifying only on create. Contacts created two years ago never re-fire the function, and those are precisely the ones whose status may have changed.
3. Storing status without a date. An undated Active is not a verification, it is a memory.
4. Blocking the save on the API call. If the upstream is slow, your team feels it on every contact. Move to a scheduled sweep rather than accepting a laggy form.
5. Ignoring the branch GSTIN problem. A customer operating in several states has one GSTIN per state, and the one on the contact must match the place of supply on the invoice — see the GST state code list.

Frequently asked questions