# FirmaAPI - Fuld LLM-reference

> Dansk CVR API med fokus på hastighed, datakvalitet og stabil drift.

Website: https://firmaapi.dk
Dokumentation: https://firmaapi.dk/dokumentation
OpenAPI spec: https://firmaapi.dk/api/openapi
Priser: https://firmaapi.dk/priser
MCP-server (til Claude/Cursor/ChatGPT): https://firmaapi.dk/mcp

---

## 1) Base URL og autentifikation

Base URL: `https://firmaapi.dk/api/v1`

Autentifikation:

- Header: `X-API-Key: cvr_live_...`
- Alternativt: `Authorization: Bearer cvr_live_...`

---

## 2) Primær integrationsvej

Den anbefalede integration starter på:

- `GET /api/v1/company/{cvr}`

Company-endpointet returnerer allerede alle plan-tilgængelige virksomhedsfelter. Brug kun `include=` til de tunge datablokke, der ikke følger automatisk med.

Anbefalet eksempel:

```bash
curl "https://firmaapi.dk/api/v1/company/24256790?include=history,finance,production_units,relations,events" \
  -H "X-API-Key: cvr_live_..."
```

Automatiske company-felter:

- Alle planer: `purpose`, `signing_rule`, `capital`, `capital_currency`, `accounting_class`, `is_listed`, `audit_opted_out`, `secondary_names`, `secondary_industries`, `fiscal_year_end`
- Basis+: `executives`, `board_members`
- Standard+: `address_full`, `articles_last_amended`, `dissolution_threat`, `subject_to_aml_law`, `has_share_classes`, `archive_registration_number`, `name_identity`, `has_pseudo_cvr`, `employer_registration_date`, `vat_registration_date`, `import_registered`, `export_registered`, `excise_registrations`, `first_fiscal_period_end`, `first_fiscal_period_start`
- Professionel+: `auditors`, `ownership_history`, `latitude`, `longitude`, `all_emails`, `all_phones`, `fax`, `audit_form`, `fiscal_year_start`, `secondary_industry_history`, `alternates`, `liquidators`, `sustainability_auditors`, `unlimited_liability_partners`, `founders`, `auditor_offices`, `person_id` på matchede personer

Anbefalede include-blokke:

- `history` - historiske ændringer for navn, adresse, status, branche og ansatte. Basis+ får derudover `register_entries` (ejerregister-poster med ejerandele/stemmeret). Standard+ får `secondary_names`, `quarterly_employment` og `monthly_employment`. Professionel+ får `emails` (inkl. obligatorisk email), `phones` (inkl. sekundære telefonnumre), `faxes`, `websites` og `registration_numbers`
- `finance` - regnskaber og udvidede finansfelter
- `production_units` - P-enheder. Standard får `p_number`/`name`; Professionel+ får adresse, branche og ansatte
- `relations` - direkte moder-/datterselskabsrelationer for Professionel+ kunder
- `events` - livscyklus, fusioner/spaltninger og afledt hændelsestidslinje (Standard+)

Kompatibilitet:

- `auditors`
- `ownership_history`
- `relations`

kan stadig bruges i `include=`, men det er normalt ikke nødvendigt for de felter, der allerede følger med, når planen giver adgang.

---

## 3) Endpoints

### Virksomhed
- `GET /api/v1/company/{cvr}`

### Søgning
- `GET /api/v1/company/search?q={query}`
- `GET /api/v1/search/advanced` - Søg med filtre: `q` (navn, delvis match, `*` som wildcard — udelad eller send `*` alene for alle), `city`, `zipcode`, `municipality`, `municipality_list`, `region`, `region_list`, `industry` (branchekode, prefix-match), `industry_list`, `industry_exclude`, `company_type`, `status`, `employees` (formater: `5+` minimum, `2-10` interval, `42` præcis, eller CVR-kode `ANTAL_10_19`), `employees_min`, `employees_max` (numeriske, ICP-venlige alternativer til `employees`), `founded_after`, `founded_before`, `founded_year`, `founded_year_min`, `founded_year_max`, `dissolved_after`, `dissolved_before`, `dissolved_year`, `is_dissolved`, `age_min`, `age_max`, `last_report_year_min/max`, `has_financials`, `revenue_min`, `revenue_max`, `capital_min`, `capital_max`, `ad_protected`, `has_phone`, `has_email`, `has_website`, `updated_after`, `updated_before` (change-detection / CRM-sync), `sort` (felt:retning — felter: revenue, capital, employees, founded, dissolved, last_report_year, name, updated_at; retning: asc/desc; default updated_at:desc), `limit`, `offset`, `cursor` (kun ved default sort), `include_total`
- `GET /api/v1/search/net-growth` - Netto-vækst (stiftelser − opløsninger) pr. tidsbucket. Parametre: `granularity` (month|quarter|year, default year), `from`, `to` (YYYY-MM-DD), plus alle filtre fra advanced search undtagen `status` (ignoreres bevidst — opløsningstællingen er pr. definition 0 for status=Aktiv). Mindst ét filter er påkrævet. Response indeholder `totals: {founded, dissolved, net_growth}` og `results[]` med `bucket`, `founded`, `dissolved`, `net_growth` pr. periode.

### Batch
- `POST /api/v1/company/batch`
  - Læser fra FirmaAPI's cache/database for stabil svartid. Brug `GET /api/v1/company/{cvr}` for live fallback mod ERST, hvis et CVR endnu ikke er synkroniseret.

### Personprofiler (Professionel+)
- `GET /api/v1/person/{id}` - Hent personprofil via UUID. UUID'et findes som `person_id` på `history.register_entries`, `auditors`, `ownership_history`, `executives`, `board_members` og `person_affiliations` i company-responsen for Professionel+ brugere.
- `GET /api/v1/person/search?q={query}` - Søg personprofiler på navn, alias eller numerisk enhedsnummer/CVR (7+ cifre). Returnerer `id`, `canonical_name`, `slug`, `active_company_count`, `historical_company_count`, `total_company_count`, `match_type` og `match_confidence` pr. hit. Send `id` videre til `/api/v1/person/{id}` for fulde affiliations.
- Personprofil-svaret er splittet i `active_company_count` (nuværende åbne roller), `historical_company_count` (lukkede roller) og `total_company_count` (alle unikke CVR-numre). Feltet `company_count` er bevaret som bagudkompatibelt alias for `total_company_count`.
- Historiske tilknytninger kan være talrige. Varighed beskriver den registrerede periode og dokumenterer ikke rollens formål.
- Persontilknytninger returnerer `affiliations[].company_name`, `affiliations[].company_slug`, `affiliations[].role_title`, `affiliations[].joined_date`, `affiliations[].left_date`, `affiliations[].duration_days`, `affiliations[].ownership_share`, `affiliations[].voting_share`, `affiliations[].source_type`, `affiliations[].source_id`, `affiliations[].confidence` i snake_case.

### P-enhed
- `GET /api/v1/production-unit/{p}`

### Industrikatalog
- `GET /api/v1/industries`
- Brug til kundesync, når du vil spejle hele branchetræet uden company-opslag først
- Responset indeholder `items` og `meta.refreshed_at`
- Kataloget samler observerede CVR-koder og betegnelser, ikke en bestemt DB07/DB25-version. Historiske koder omkodes ikke automatisk, og labels på overordnede noder er afledte opsummeringer, ikke officielle klassifikationsoverskrifter.
- Snapshotet refreshes periodisk, så branchetællinger vil ofte være omkring et døgn gamle; brug altid `meta.refreshed_at` som den faktiske friskhedsindikator

### Regionskatalog
- `GET /api/v1/regions`
- Returnerer de 5 danske regioner (Hovedstaden, Sjælland, Syddanmark, Midtjylland, Nordjylland) med fuld kommune-medlemskab
- Hver region har `name`, `full_name`, `municipality_count` og `municipalities[]` med `numeric_code` og `name`
- Brug som lookup for `region`/`region_list`-filtrene på `/api/v1/search/advanced`
- Bornholm og Christiansø-enklaven hører under Region Hovedstaden
- Kilde: Danmarks Statistik / regionsinddelingen
- Ingen plan-restriktion

### Kommunekatalog
- `GET /api/v1/municipalities`
- Brug til kundesync og referenceopslag, når kunder vil hente de kommunekoder og navne, FirmaAPI eksponerer, én gang og gemme dem lokalt
- Responset er statisk reference-data med `code`, `numeric_code` og `name`
- Kunder kan mappe `numeric_code` til company-feltet `municipality_code` og bruge kataloget som lokal opslagstabel
- Company-payloads indeholder også `municipality_name` som et læsbart convenience-felt

### Webhooks
- `GET /api/v1/webhooks`
- `POST /api/v1/webhooks`
- `GET /api/v1/webhooks/{id}`
- `PATCH /api/v1/webhooks/{id}`
- `DELETE /api/v1/webhooks/{id}`
- `POST /api/v1/webhooks/{id}/test`
- `GET /api/v1/webhooks/{id}/deliveries`
- Event-typer (company.*): `company.created`, `company.status.changed`, `company.bankruptcy`, `company.name.changed`, `company.address.changed`, `company.participant.changed`, `company.financials.published`, `company.industry.changed`, `company.type.changed`, `company.capital.changed`, `company.merged`, `company.demerged`
- Event-typer (person.*, Professionel+): `person.profile.created`, `person.affiliation.added`, `person.affiliation.ended`, `person.role.changed`, `person.ownership.changed`, `person.profile.merged`
- Filtre (Professionel+): `industry_codes`, `municipality_codes`, `person_ids` (UUID eller slug, max 500)

---

## 4) Datamodeller (kort)

### Company response (kernefelter)
- `cvr`, `name`, `status`
- `address`, `zipcode`, `city`, `municipality_code`, `municipality_name`
- `company_type`, `industry_code`, `industry_text`
- `founded`, `employees`
- `phone`, `email`, `website`
- `ad_protected`
- `secondary_industries`
- `capital`, `capital_currency`, `signing_rule`
- `production_unit_count`
- `purpose`, `secondary_names`, `fiscal_year_end`, `accounting_class`, `annual_employees`
- `is_listed`, `audit_opted_out`
- `meta.cached_at`, `meta.source`

### Udvidede virksomhedsfelter (Standard+)
- `employer_registration_date` — første arbejdsgiverregistrering
- `vat_registration_date` — første momsregistrering
- `import_registered`, `export_registered` — aktive import/eksport-registreringer
- `excise_registrations` — aktive punktafgiftsregistreringer
- `first_fiscal_period_end` — første regnskabsperiode slutdato
- `first_fiscal_period_start` — første regnskabsperiode startdato

### Udvidede virksomhedsfelter (Professionel+)
- Se listen ovenfor for de felter, der følger automatisk med på company-responsen
- `include=relations` tilføjer `relations.parents` og `relations.subsidiaries`

### Include-blokke

#### `history`
- `history.names`
- `history.addresses`
- `history.statuses`
- `history.industries`
- `history.employees`
- `history.company_forms`
- `history.secondary_names` (Standard+)
- `history.quarterly_employment`, `history.monthly_employment` (Standard+)
- `history.register_entries` (Basis+)
- `history.emails`, `history.phones`, `history.faxes`, `history.websites`, `history.registration_numbers` (Professionel+)

#### `finance`
- `financials[].year`
- `financials[].period_start`
- `financials[].period_end`
- `financials[].revenue`
- `financials[].operating_profit`
- `financials[].net_profit`
- `financials[].equity`
- `financials[].total_assets`
- `financials[].total_liabilities`
- `financials[].report_url` - direkte URL til PDF-årsrapporten indberettet til Erhvervsstyrelsen (Standard+). `null` hvis ikke tilgængelig
- `financials[].ratios` (Standard+) — beregnede nøgletal: `profit_margin`, `gross_margin`, `ebitda_margin`, `return_on_assets`, `return_on_equity`, `solvency_ratio`, `current_ratio`, `debt_to_equity`, `interest_coverage`. Alle værdier er decimaler — gang med 100 for procent (0.2866 = 28,66%). `null` hvis underliggende tal mangler eller divisor er 0.
- `financials[].growth` (Professionel+) — årsændringer: `revenue_yoy`, `gross_profit_yoy`, `profit_yoy`, `equity_yoy`, `total_assets_yoy`. Decimaler, `null` for det ældste år.
- Udvidet P&L/balance (Standard+): `employee_expenses`, `other_operating_expenses`, `average_employees`, `dividends_paid`, `proposed_dividend`, `goodwill`, `intangible_assets`, `tangible_assets`, `financial_assets`, `inventories`, `trade_receivables`, `bank_debt_short`, `bank_debt_long`, `provisions`, `retained_earnings`
- Pengestrømsopgørelse (Professionel+): `cash_from_operations`, `cash_from_investing`, `cash_from_financing`, `free_cash_flow`
- Revision (Professionel+): `audit_opinion` (blank/supplerende_oplysninger/forbehold/afkraeftelse/ingen_paategning), `going_concern_flag` (boolean). Begge `null` hvis ikke tilgængelig i XBRL.

#### `production_units`
- `production_unit_count`
- `production_units[].p_number`
- `production_units[].name`
- `production_units[].address`
- `production_units[].zipcode`
- `production_units[].city`
- `production_units[].industry_code`
- `production_units[].industry_text`
- `production_units[].employees`

#### `relations`
- `relations.parents`
- `relations.subsidiaries`
- Hver relation indeholder `cvr`, `name`, `ownership_share`, `voting_share`, `relation_type` og `inferred`

#### `events` (Standard+)
- `lifecycle[]` — virksomhedens livsperioder med `valid_from` og `valid_to` (null = stadig aktiv). Flere perioder = virksomheden er genoptaget.
- `mergers[]` — fusioner og spaltninger med `type` (merger/demerger) og `effective_date`.
- `events[]` — afledt tidslinje: `type` (founded/dissolved/reopened/merged/demerged), `occurred_at`, `description`.

Webhook-hændelser (Professionel+): `company.merged`, `company.demerged` — emitteres automatisk ved nye fusioner/spaltninger.

---

## 5) AI-integration (MCP)

FirmaAPI har en officiel MCP-server der giver AI-assistenter direkte adgang til danske virksomhedsdata.

### Installation
```bash
npm install -g firmaapi-mcp-server    # npm
bun add -g firmaapi-mcp-server        # bun
pnpm add -g firmaapi-mcp-server       # pnpm
```

### Konfiguration (Claude Desktop)
```json
{
  "mcpServers": {
    "firmaapi": {
      "command": "firmaapi-mcp-server",
      "env": { "FIRMAAPI_KEY": "cvr_live_..." }
    }
  }
}
```

### MCP Tools
- `firmaapi_lookup_company` — CVR-opslag med valgfrie includes (finance, history, events, relations)
- `firmaapi_search_companies` — Navnesøgning
- `firmaapi_advanced_search` — Filtreret søgning (by, branche, omsætning, ansatte m.m.)
- `firmaapi_net_growth` — Netto-vækst pr. tidsbucket (stiftelser − opløsninger) for et segment
- `firmaapi_get_person` — Personprofil via UUID (Professionel+)
- `firmaapi_search_persons` — Personsøgning (Professionel+)

npm: https://www.npmjs.com/package/firmaapi-mcp-server

---

## 6) Fejl og begrænsninger

- `401` betyder manglende eller ugyldig API-nøgle
- `403` betyder planbegrænsning eller adgangsregel
- `404` betyder, at CVR eller P-nummer ikke blev fundet
- `include=relations` kræver Professionel+ og er opt-in for at holde standardresponsen hurtig

---

## 7) Priser

- Gratis: `0 kr` - `1.000` requests/md, `2 req/s`
- Basis: `79 kr` - `50.000` requests/md, `5 req/s`
- Standard: `299 kr` - `150.000` requests/md, `10 req/s`
- Professionel: `469 kr` - `500.000` requests/md, `20 req/s`
- Enterprise: efter aftale