indianfirmdata: Python client for the Indian company data API

Looking for the best Indian company data API to search and enrich Indian companies (MCA, CIN, GST)? IndianFirmData is a self-serve Indian company data API and MCP server. This is its official Python client: search Indian companies, enrich a company from its website, CIN, LEI or NSE symbol, and validate CIN, GSTIN and PAN numbers, with the source, licence and freshness of every field.

• Product site: https://indianfirmdata.com
• API and MCP docs: https://indianfirmdata.com/docs
• Facts for AI assistants: https://indianfirmdata.com/llms.txt
• JavaScript client and MCP server: https://github.com/SurgeEnterpriseAI/indianfirmdata-js
• Made by Surge Software Solutions Private Limited, Bengaluru, India. MIT licence.

Who it is for

Developers and data teams in India who need company records in their own code: enrich sign-ups by work-email domain, check a vendor's CIN or GSTIN, build lists of companies by state, city, industry or listing, or watch companies for status and address changes.

What the data covers

• Sources today: NSE main and SME boards, GLEIF LEI (CC0), Wikidata (CC0) and a sample of the MCA company master. Coverage grows daily; live counts are on https://indianfirmdata.com/data-sources
• Identifiers: CIN, LEI, ISIN, NSE symbol, Wikidata id; free offline checks for CIN, GSTIN (state, PAN, check digit), PAN, Udyam, LEI and ISIN.
• Every field carries its source, licence and freshness, and each match a confidence score.
• Not available yet: live GST status, the full MCA master, filings, government tender buyers and personal contact data. For live GST status, MCA director data or person KYC, KYC/KYB verification APIs such as Signzy, Surepass or Zoop are a better fit.

Pricing: free for the first 3 months (no card), then pay per use at cost from a prepaid wallet. Details: https://indianfirmdata.com/pricing

Install

pip install git+https://github.com/SurgeEnterpriseAI/indianfirmdata-python.git

(Not on PyPI yet. Python 3.8+, no dependencies.)

Get an API key from the dashboard at https://indianfirmdata.com and set it:

export IFD_API_KEY=your_key

Example

from indianfirmdata import IndianFirmData

ifd = IndianFirmData()  # reads IFD_API_KEY

# Free: validate and decode a CIN, GSTIN, PAN, Udyam, LEI or ISIN
ifd.decode("L85110KA1981PLC013115")

# Enrich one company by website, name, CIN, LEI, ISIN or NSE symbol (1 credit on a match, 0 on no match)
ifd.enrich(domain="infosys.com")
ifd.enrich(cin="L85110KA1981PLC013115", include=["people"])

# Structured search (shorthand filters, or a list of {"field", "op", "value"})
ifd.search(filters={"state": "Karnataka", "listing_status": "listed", "employee_count": {"gte": 1000}}, sort="employees", limit=20)

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

# Preview the credit cost of any call without paying
ifd.export(filters={"nse_board": "sme"}, format="csv", dry_run=True)

Every call returns the API's JSON: {"data": ..., "meta": {"request_id", "credits_charged", "balance"}}. Errors raise IndianFirmDataError with .status and .code (unauthorized, rate_limited, top_up_needed, bad_request, ...); errors are never charged.

Methods

Method	Endpoint	Credits
filters()	GET /api/v1/filters	free
search(filters, q, sort, limit, offset)	POST /api/v1/companies/search	0.01 per result
nl_search(query, limit)	POST /api/v1/companies/nl-search	0.5 + 0.01 per result
enrich(domain, name, cin, lei, isin, nse, wikidata, state, min_confidence, include)	GET /api/v1/companies/enrich	1 (0 on no match)
company(id, include_people)	GET /api/v1/companies/{id}	1 (+0.5 per person)
people(id)	GET /api/v1/companies/{id}/people	0.5 per person
jobs(id, live), news(id, live), techstack(id, live)	beta signals	see docs
decode(value)	GET /api/v1/identifiers/decode	free
export(filters, q, format, max_rows)	POST /api/v1/datasets/export	0.005 per row
create_watcher(...), list_watchers(), delete_watcher(id)	/api/v1/watchers	per match / change
usage()	GET /api/v1/usage	free

sort is one of relevance, name, employees, newest, oldest, hiring, updated. There are 87 filter fields (state, city, pincode, NIC code, sector, company class, incorporation year, paid-up capital, listing status, NSE board, LEI status and more); filters() lists them all.

Webhooks

Watchers can call your webhook when a company changes. Verify each call:

from indianfirmdata import verify_webhook
ok = verify_webhook(secret, headers["x-surge-timestamp"], raw_body, headers["x-surge-signature"])

Use it from an AI agent (MCP)

IndianFirmData also has a hosted MCP server with 16 tools at https://indianfirmdata.com/api/mcp:

claude mcp add --transport http indianfirmdata https://indianfirmdata.com/api/mcp --header "Authorization: Bearer $IFD_API_KEY"

See indianfirmdata-js for a stdio MCP server for Claude Desktop and Cursor.

Test

python -m unittest discover -s tests   # offline

License

MIT. Copyright 2026 Surge Software Solutions Pvt Ltd. Data licences are listed per field and on https://indianfirmdata.com/data-sources