Use cases · for Python developers and data teams

Indian company data in Python: the indianfirmdata client

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

indianfirmdata is the official, open-source (MIT) Python client for the IndianFirmData API. Install it with pip install git+https://github.com/SurgeEnterpriseAI/indianfirmdata-python.git, set IFD_API_KEY, and call ifd.decode() to check a CIN or GSTIN for free, ifd.enrich() to get a company by CIN, LEI, ISIN, NSE symbol, website or name, ifd.search() or ifd.nl_search() to build lists, and ifd.export() for CSV. It needs Python 3.8+ and has no dependencies.

Steps in IndianFirmData

1. Install the client
pip install git+https://github.com/SurgeEnterpriseAI/indianfirmdata-python.git. It is not on PyPI yet. Python 3.8 or later; it uses only the standard library.
2. Create an API key
Sign up free, open Dashboard → API keys, create a key and set it as IFD_API_KEY in your environment. The client reads it automatically.
3. Decode and enrich
ifd.decode(value) checks a CIN, GSTIN, PAN, Udyam, LEI or ISIN for 0 credits. ifd.enrich(cin=...) or enrich(domain=...) returns the company record; 1 credit on a match, 0 otherwise.
4. Search and export
ifd.search(filters=..., sort=..., limit=...) runs a structured search over 87 fields at 0.01 credits a result; ifd.nl_search("...") takes plain English; ifd.export(..., format="csv") returns a file. Pass dry_run=True to any of them to see the cost first.

Example

from indianfirmdata import IndianFirmData, IndianFirmDataError

ifd = IndianFirmData()  # reads IFD_API_KEY

# Free: validate and decode a CIN, GSTIN, PAN, Udyam, LEI or ISIN
cin = ifd.decode("L85110KA1981PLC013115")["data"]
print(cin["valid"], cin["decoded"]["state"], cin["decoded"]["incorporationYear"])

# Enrich one company (1 credit on a match, 0 on no match)
res = ifd.enrich(domain="infosys.com")["data"]
if res.get("company"):
    c = res["company"]
    print(c["name"], c["cin"], res["match"]["method"], res["match"]["confidence"])

# Structured search: shorthand filters, or a list of {"field", "op", "value"}
page = ifd.search(filters={"state": "Karnataka", "listing_status": "listed"}, sort="employees", limit=20)["data"]
for row in page["results"]:
    print(row["name"], row["cin"], row["city"])

# Plain-English search
ifd.nl_search("listed IT companies in Pune")

# See the cost of an export before paying for it
print(ifd.export(filters={"nse_board": "sme"}, format="csv", dry_run=True)["meta"])

try:
    ifd.enrich(cin="not-a-cin")
except IndianFirmDataError as e:
    print(e.status, e.code)   # errors are never charged

What every call returns

Each method returns the API's JSON as a dict: {"data": ..., "meta": {"request_id", "credits_charged", "balance"}}. Errors raise IndianFirmDataError with .status and .code, for example unauthorized, rate_limited, top_up_needed or bad_request. Errors are never charged.

The client also has company(), people(), watchers (create_watcher, list_watchers, delete_watcher), usage() and verify_webhook() for signed watcher webhooks. The source is on GitHub: https://github.com/SurgeEnterpriseAI/indianfirmdata-python.

When IndianFirmData is not the right tool

If you need an async client, pandas integration or retries built in, the client does not provide them yet: it is a thin, dependency-free wrapper, so add your own backoff on rate_limited. The data limits are the API's: no live GST status, no full MCA master and no personal contact data.

Questions

Is the Python client on PyPI?

Not yet. Install it from GitHub with pip install git+https://github.com/SurgeEnterpriseAI/indianfirmdata-python.git.

Which Python versions does it support?

Python 3.8 and later. It has no dependencies outside the standard library.

Can I point it at a different base URL?

Yes. Pass base_url=... or set IFD_API_URL; the default is https://indianfirmdata.com.

Is there a JavaScript version?

Yes, indianfirmdata-js, with the same methods in camelCase and a stdio MCP server for Claude Desktop and Cursor.

Try it on a company you know.

Start free — 3 months on us