Use cases · for JavaScript and TypeScript developers

Indian company data in Node.js and TypeScript

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

indianfirmdata-js is the official, open-source (MIT) JavaScript client for the IndianFirmData API, with TypeScript types. Install it with npm install github:SurgeEnterpriseAI/indianfirmdata-js, set IFD_API_KEY, then use decode() for free CIN and GSTIN checks, enrich() for a company by CIN, LEI, ISIN, NSE symbol, website or name, search() and nlSearch() for lists, and export() for CSV. It runs on Node.js 18+ with no dependencies for the API client, and the same package includes a stdio MCP server.

Steps in IndianFirmData

1. Install the package
npm install github:SurgeEnterpriseAI/indianfirmdata-js. It is not on the npm registry yet. Node.js 18 or later (it uses the built-in fetch).
2. Set your API key
Create a key in Dashboard → API keys and set IFD_API_KEY, or pass { apiKey } to the constructor.
3. Call the API
await ifd.enrich({ cin }) returns the company record (1 credit on a match, 0 otherwise); await ifd.decode(value) checks an ID for free; search, nlSearch and export build lists. Pass { dryRun: true } to see the cost first.
4. Handle errors
Errors throw IndianFirmDataError with status and code (unauthorized, rate_limited, top_up_needed, bad_request and so on). Errors are never charged.

Example

import { IndianFirmData, IndianFirmDataError } from "indianfirmdata";

const ifd = new IndianFirmData(); // reads IFD_API_KEY

// Free: check a GSTIN or CIN and read its parts
const { data: id } = await ifd.decode("L85110KA1981PLC013115");
console.log(id.valid, id.decoded.state);

// Enrich a sign-up from its work-email domain (1 credit on a match, 0 otherwise)
const email = "[email protected]";
const { data } = await ifd.enrich({ domain: email.split("@")[1], minConfidence: 0.9 });
if (data.company) console.log(data.company.name, data.company.cin, data.match.confidence);

// Structured search
const { data: page } = await ifd.search({ filters: { state: "Maharashtra", city: "Pune", listing_status: "listed" }, limit: 20 });
console.log(page.total, page.results.map((r) => r.name));

// Preview the cost of an export without paying
const { meta } = await ifd.export({ filters: { nse_board: "sme" }, format: "csv", dryRun: true });
console.log(meta.credits_charged);

try {
  await ifd.enrich({ cin: "not-a-cin" });
} catch (e) {
  if (e instanceof IndianFirmDataError) console.log(e.status, e.code);
}

Verify a watcher webhook

import { verifyWebhook } from "indianfirmdata";

// rawBody must be the exact request body string
const ok = verifyWebhook(secret, req.headers["x-surge-timestamp"], rawBody, req.headers["x-surge-signature"]);

Where it runs

Use it on your server, in a serverless function or in a build script. Do not ship your API key to a browser: anyone could read it from the page. Call the API from your backend and pass only the fields you need to the front end.

The source, types and tests are on GitHub: https://github.com/SurgeEnterpriseAI/indianfirmdata-js.

When IndianFirmData is not the right tool

If you need a browser-side SDK, that is by design not offered, because the key must stay secret. The data limits are the API's: no live GST status, no full MCA master and no personal contact data.

Questions

Is it on npm?

Not on the npm registry yet. Install it from GitHub with npm install github:SurgeEnterpriseAI/indianfirmdata-js.

Does it work with TypeScript?

Yes. It ships index.d.ts with types for every method, filter conditions and sort options.

Does it include the MCP server?

Yes. The same package runs a stdio MCP server with npx -y github:SurgeEnterpriseAI/indianfirmdata-js, for Claude Desktop, Cursor and other stdio clients.

Can I use it with Deno or Bun?

It is written for Node.js 18+ using standard fetch; we have not tested other runtimes.

Try it on a company you know.

Start free — 3 months on us