Quickstart¶

Goal: your first successful FirmaDB call in 90 seconds.

1. Get your API key¶

Sign up at firmadb.com/signup. The Free tier gives you 1,000 results/month with no credit card — plenty for evaluation, demos, or a small workflow.

You'll receive a key that looks like:

fdb_live_sk_aB12cD34eF56_7Hk2QmRn8wXz4PvY3LjB6Tab5mDf9xKc_a1B2c3

Set it as an environment variable so you don't paste it into requests:

export FIRMADB_API_KEY="fdb_live_sk_..."

Secret keys (sk) are server-side only

The sk class key has full account access. Never embed it in client-side code or share it with agents. For agent integrations and constrained environments, use a restricted key (rk) instead.

2. Make your first request¶

Look up L'Oréal by its French SIREN (552120222):

cURLPythonTypeScript

curl https://api.firmadb.com/v1/companies/FR/552120222 \
  -H "Authorization: Bearer $FIRMADB_API_KEY"

import os
import httpx

api_key = os.environ["FIRMADB_API_KEY"]
resp = httpx.get(
    "https://api.firmadb.com/v1/companies/FR/552120222",
    headers={"Authorization": f"Bearer {api_key}"},
)
resp.raise_for_status()
company = resp.json()
print(company["name"], "-", company["status"])

const apiKey = process.env.FIRMADB_API_KEY!;
const resp = await fetch(
  "https://api.firmadb.com/v1/companies/FR/552120222",
  { headers: { Authorization: `Bearer ${apiKey}` } },
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const company = await resp.json();
console.log(company.name, "-", company.status);

3. Understand the response¶

{
  "object": "company",
  "country": "FR",
  "registry_id": "552120222",
  "name": "L'Oreal",
  "legal_form": "SA a conseil d'administration",
  "status": "active",
  "status_active": true,
  "registered_date": "1963-12-31",
  "address": {
    "street": "14 Rue Royale",
    "city": "Paris",
    "postal_code": "75008",
    "country": "FR"
  },
  "nace_code": "20.42Z",
  "nace_description": "Manufacture of perfumes and toilet preparations",
  "employee_count": 87400,
  "website": "https://www.loreal.com",
  "source_url": "https://annuaire-entreprises.data.gouv.fr/etablissement/55212022200016",
  "data_freshness": {
    "record_retrieved_at": "2026-05-04T02:15:00Z",
    "country_dataset_updated_at": "2026-05-04T02:00:00Z",
    "freshness_status": "current",
    "max_age_days": 7
  },
  "request_id": "req_01HZAB7MJX9V8GG6P3K5R2QC4N"
}

The fields you'll use most:

Field	What it tells you
`name`	Official registered name as filed with the registry.
`status`	Normalized status: `active`, `dissolved`, `suspended`, `liquidation`, or `unknown`.
`status_active`	Convenience boolean. `true` for active, `false` for dissolved/suspended/liquidation, `null` for unknown.
`source_url`	Direct link to the government registry page for this record — auditable, ungameable.
`data_freshness.country_dataset_updated_at`	When the country's registry data was last loaded.
`request_id`	Echoed in the `X-Request-Id` response header. Quote this when contacting support.

Search is free — only resolved lookups consume your monthly results

GET /v1/companies/search and 404s on /v1/companies/{country}/{id} cost zero billable results. Only successful exact lookups, batch matches, and verifications count toward your 1,000 monthly results on the Free tier.

4. What's next?¶

Pick the path that matches your use case:

I have names, not registry IDs

Use the search endpoint, then look up the winner by ID. → Search by Name, Then Look Up by ID

I have a CRM list of companies to enrich

Batch up to 100 (country, registry_id) pairs per call with POST /v1/companies/lookup-batch. → CRM Enrichment guide

I need to check if a company is active (KYB)

Use firmadb_verify_status (MCP) or hit the lookup endpoint and read status_active. → KYB Status Verification

I'm building an AI agent

Connect to the hosted MCP server at mcp.firmadb.com/mcp. → MCP Setup

Common next steps¶

API Reference — every endpoint, every parameter, interactive try-it-out.
Errors — every error shape, what it means, how to fix it.
Authentication — key formats, scopes, restricted keys, rotation.