API & MCP documentation

Base URL https://indianfirmdata.com (local: http://localhost:6350). Authenticate with Authorization: Bearer <key>. Create keys in the dashboard.

Every response is { data, meta: { request_id, credits_charged, balance } }. Add ?dry_run=true to any call to see its credit cost without paying. Errors return { error: { code, message } } and are never charged.

Endpoints

Quick start

# Enrich by CIN, domain or name
curl "$BASE/api/v1/companies/enrich?domain=infosys.com" -H "Authorization: Bearer $KEY"

# Structured search (shorthand or [{field, op, value}])
curl -X POST "$BASE/api/v1/companies/search" -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"filters": {"state": "Karnataka", "listing_status": "listed", "employee_count": {"gte": 1000}}, "sort": "employees", "limit": 20}'

# Natural language
curl -X POST "$BASE/api/v1/companies/nl-search" -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"query": "Pune SaaS firms hiring AEM devs"}'

# Watch for changes (webhook signed with HMAC-SHA256)
curl -X POST "$BASE/api/v1/watchers" -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"kind": "company", "company_ids": ["co_..."], "fields": ["entity_status","address"], "webhook_url": "https://example.com/hook"}'

MCP server (16 tools)

Remote (HTTP): add https://indianfirmdata.com/api/mcp with header Authorization: Bearer <key> to any MCP client that supports Streamable HTTP.

Local (stdio) for Claude Desktop / Claude Code:

{
  "mcpServers": {
    "indianfirmdata": {
      "command": "npx",
      "args": ["tsx", "D:/projects/surge-products/company-data/mcp/stdio.ts"],
      "env": { "IFD_API_URL": "https://indianfirmdata.com", "IFD_API_KEY": "scd_..." }
    }
  }
}

Webhook verification

const expected = hmacSha256Hex(secret, `${req.headers["x-surge-timestamp"]}.${rawBody}`);
const ok = req.headers["x-surge-signature"] === "v1=" + expected;

Filters: 84 fields, 433 field-operator filters