Use cases · for KYB, risk and onboarding engineers

How to verify an Indian company before onboarding (KYB) by API

Last updated 11 November 2026 · by Venu Gopal Reddy Muvva, founder

To verify an Indian business before you onboard it: check that the CIN and GSTIN it gave you are well formed, find the company in a registry-backed record, compare its status, legal name and state with what you were told, keep the source and date of each fact, and watch it for changes after onboarding. IndianFirmData does all five through one API, free for 3 months: the ID checks cost 0 credits and a company match costs 1. It does not do live GST status, director (DIN) checks or person KYC, so regulated onboarding usually adds a licensed KYC vendor for those steps.

Steps in IndianFirmData

  1. 1. Check the IDs the business gave you

    Call GET /api/v1/identifiers/decode?value=<CIN or GSTIN>. It costs 0 credits. A failed check digit means the number was mistyped or made up. For a GSTIN you also get the state code, the PAN inside it and the PAN holder type (company, firm or LLP, individual and so on).

  2. 2. Find the company record

    Call GET /api/v1/companies/enrich?cin=<CIN>. A match costs 1 credit and no match costs nothing. Without a CIN, pass name and state, and set min_confidence (for example 0.9) so a weak name match comes back as no match instead of the wrong company.

  3. 3. Compare what you were told with the record

    Check entity_status, legal_name and state on the record. Compare the GSTIN's state with the registered state; a business can hold GSTINs in several states, so a difference is a question for the applicant, not an automatic fail.

  4. 4. Keep the evidence

    Store meta.request_id, the field_sources list (source, value and date of each field) and the freshness block, which flags any field older than its freshness limit. That is your audit trail of what you checked and when.

  5. 5. Watch the company after onboarding

    POST /api/v1/watchers with kind company, the company id and fields such as entity_status and address. You get an email and, if you give a webhook_url, a signed webhook when a watched field changes.

The same flow in Python

from indianfirmdata import IndianFirmData

ifd = IndianFirmData()  # reads IFD_API_KEY

def kyb_check(cin, gstin=None):
    report = {"cin": cin, "flags": []}
    cin_id = ifd.decode(cin)["data"]                      # 0 credits
    if not cin_id["valid"]:
        report["flags"].append("CIN fails the format check")
        return report
    g = ifd.decode(gstin)["data"] if gstin else None      # 0 credits
    if g and not g["valid"]:
        report["flags"].append("GSTIN fails the checksum")
    elif g and g["decoded"]["holder_type"] != "company":
        report["flags"].append("PAN inside the GSTIN is not a company PAN")

    res = ifd.enrich(cin=cin)["data"]                     # 1 credit on a match, 0 otherwise
    company = res.get("company")
    if not company:
        report["flags"].append("Not in the index: check this company another way")
        return report
    report.update(name=company["name"], status=company.get("entity_status"), state=company.get("state"))
    if report["status"] and report["status"].upper() != "ACTIVE":
        report["flags"].append("Status is " + report["status"])
    if g and g["valid"] and (g["decoded"]["state"] or "").lower() != (company.get("state") or "").lower():
        report["flags"].append("GSTIN state differs from the registered state (could be a branch)")
    report["stale_fields"] = [f for f, v in company["freshness"].items() if v["stale"]]
    report["evidence"] = company["field_sources"]
    return report

Watch it after onboarding (curl)

curl -X POST "https://indianfirmdata.com/api/v1/watchers" \
  -H "Authorization: Bearer $IFD_API_KEY" -H "content-type: application/json" \
  -d '{"kind": "company", "company_ids": ["co_..."], "fields": ["entity_status", "address"], "webhook_url": "https://example.com/hook"}'

What this check proves, and what it does not

It proves the IDs are well formed, that a company with that CIN exists in a public registry source we hold, and what that source says about its status, name and state, with dates. It does not prove that the person applying works for that company, that its GST registration is active today, or who its directors are. Those need person KYC, a licensed GSP and MCA director data, which IndianFirmData does not offer.

When IndianFirmData is not the right tool

If you are a regulated entity and your KYB policy requires live GST status, director (DIN) verification, bank account checks or person KYC, you need a licensed KYC/KYB vendor such as Surepass, Signzy, Perfios Karza or Gridlines for those steps. IndianFirmData also holds no MCA master data yet, so many unlisted private companies will return no match.

Questions

How much does one KYB check cost?

The CIN and GSTIN checks are free. The company match is 1 credit, and nothing when there is no match. The first 3 months are free; after that you pay per use at our cost from a prepaid wallet.

Can I run this inside an AI agent?

Yes. The MCP server's decode_identifier, enrich_company and create_watcher tools do the same steps, so Claude or Cursor can run the check and quote the sources.

What if the company is not found?

You are not charged. Ask the applicant for its CIN if you searched by name, or verify it another way; the full MCA master is not in our index yet.

Try it on a company you know.

Start free — 3 months on us

Related: Check a company is real · GSTIN to company details · Watch companies for changes · IndianFirmData vs Perfios Karza · Pricing

How to verify an Indian company before onboarding (KYB) by API