# API-dokumentasjon

> Full referanse for Firmasett API v1: autentisering, konvolutt, alle endepunkter, filtre, feilkoder, MCP og CLI.


Base `https://firmasett.arnu.io/v1`. Nøkkel i `Authorization: Bearer fs_…` ([gratis i konsollen](/konsoll)). JSON inn og ut, UTF-8, norske feltnavn. Maskinlesbar beskrivelse: [openapi.json](/openapi.json). Kort versjon for agenter: [llms.txt](/llms.txt).

## Konvolutt

Alle svar:

```json
{"status": "ok | ikke_funnet | feil", "resultat": "…", "melding": "bare ved ikke_funnet", "meta": {"plan": "…", "vindu": "5 timer", "berikelser": {"grense": 0, "brukt": 0, "igjen": 0}, "sok": {"grense": 0, "brukt": 0, "igjen": 0}, "telefonpoeng": 0, "belastet": {"berikelse": 1}}}
```

`ikke_funnet` er HTTP 200 og koster ingenting. `feil` kommer med HTTP 4xx og `feil: {kode, melding, http}`.

| HTTP | kode | Når |
|---|---|---|
| 400 | `ugyldig_foresporsel` | Manglende eller ugyldig parameter; meldingen sier hvilken |
| 401 | `ugyldig_nokkel` | Mangler eller feil nøkkel |
| 403 | `ingen_telefonpoeng` | Mobilnummer finnes, men kontoen har ikke poeng |
| 429 | `kvote_brukt` | Planens søketreff eller berikelser er brukt opp i vinduet; `Retry-After` i sekunder |

## Konto (gratis)

### GET /konto
Plan, grenser, brukt, telefonpoeng.

### GET /bruk
Forbruk per dag siste 30 dager: `{dager: [{dag, berikelse, sok, telefon}]}`.

### GET /onboarding og POST /onboarding
Profilen agenten samler inn første gang: `navn, telefon, epost, firma, bestemmer, paavirker`. GET gir `{fullfort, mangler, profil, sporsmal}`. POST tar ett eller flere felt («-» = hoppet over) og svarer med ny status. Til profilen er fullført ligger `onboarding_mangler` i `meta` på alle svar, og MCP-serverens `initialize` ber agenten stille spørsmålene. Gratis.

### GET /bransjer
`{bransjer: [{kode, bransje, antall, med_dl_epost, med_dl_mobil}], fylker: [...]}`. To-sifrede næringskoder.

## Søk

### GET /selskaper/sok
Fritekst `q` (navn, daglig leder eller orgnr) pluss filtre. Svar: `{total, side, antall, treff: [SelskapKort]}`. Hvert treff som leveres teller som ett søketreff. `antall_kun=ja` gir bare `total`, gratis. Oppslag på et orgnr som ikke er i hoveddatasettet (`GET /selskaper/{orgnr}`) gir registerdata fra Enhetsregisteret gratis, med `dekning: register`; selskaper i hoveddatasettet har `dekning: full`. Driftsstatus uten nøkkel: [`/status.json`](/status.json) (siste bygg, dekning, siste nattkjøring).

`SelskapKort`: orgnr, navn, bransje_kode, bransje, ansatte, stiftet, fylke, kommune, omsetning, kundetype, hjemmeside, utestaende_anslag, kunder_anslag, daglig_leder, har_dl_epost, har_dl_mobil, har_dl_linkedin, kan_sms.

### GET /personer/sok
Samme filtre, `q` er navn. Treff: `{navn, tittel, orgnr, firma, bransje, fylke, kommune, ansatte, har_epost, har_mobil, har_linkedin}`.

### Filtre {#filtre}

| Parameter | Verdi | Virker på |
|---|---|---|
| `bransje` | NACE-prefiks, flere med komma: `69.2,85.1` | bransje_kode |
| `fylke` | Navn, flere med komma | fylke |
| `kommune` | Navn | kommune |
| `kundetype` | B2B, B2C, begge, offentlig | anslag |
| `ansatte_min`, `ansatte_maks` | tall | ansatte |
| `omsetning_min`, `omsetning_maks` | kr | siste regnskap |
| `stiftet_min`, `stiftet_maks` | år | stiftet |
| `utestaende_min`, `utestaende_maks` | kr | utestaende_anslag |
| `kunder_min`, `fakturaer_min` | tall | anslag |
| `kan_sms`, `har_dl_mobil`, `har_dl_epost`, `har_dl_linkedin`, `har_nettside`, `har_regnskap`, `fakturerer_mange`, `kjede`, `konsern` | ja / nei | flagg |
| `signal` | delstreng: purregebyr, inkasso, avtalegiro, efaktura, ehf, abonnement, nettbutikk | fakturasignaler |
| `regnskapsforer`, `revisor`, `regnskapssystem` | delstreng | roller/signaler |
| `sorter` | omsetning (standard uten `q`), ansatte, utestaende, kunder, fakturaer, nyeste, navn | |
| `antall` | 1–100, standard 25 | |
| `side` | fra 1 | |
| `antall_kun` | ja | bare tell, gratis |
| `status` | aktiv (standard), konkurs, avvikling, tvangsavvikling, alle | konkurs og avvikling er med i datasettet som signal |
| `register` | ja | søk i hele Enhetsregisteret (1,2 mill. enheter: navn, orgnr, sted, bransje, orgform) i stedet for hoveddatasettet; treffene har `dekning: register` |

Holdingselskaper og inkassoselskaper er alltid filtrert bort fra søk, men kan berikes på orgnr.

## Berikelse

### GET /selskaper/{orgnr}
1 berikelse. `resultat` = `{selskap, regnskap, anslag, signaler, roller, daglig_leder}`. Feltene står på [Våre data](/data#felt). `daglig_leder.mobil` er `tilgjengelig` eller tom; nummeret kommer fra `/telefon/finn`.

### POST /selskaper/berik
`{"orgnrs": ["…", …]}` inntil 100. `resultat: {antall, funnet, resultater: [{orgnr, status, …}]}`. 1 berikelse per funnet.

### POST /berik/person
`{"orgnr"}` eller `{"navn", "firma"}` eller `{"navn", "domene"}`. Treffer daglig leder. Hvis navnet ikke er daglig leder: `ikke_funnet` med hvem som er det (gratis). `resultat`: `navn, tittel, orgnr, firma, bransje, fylke, hjemmeside, epost, epost_kilde, epost_grad, epost_sikkerhet, epost_alternativer, har_mobil, mobil_grad, kan_sms, linkedin, linkedin_kilde, linkedin_grad, andre_selskaper`.

## Telefon

### POST /telefon/finn
`{"orgnr"}` eller `{"firma"}` eller `{"domene"}`. 1 telefonpoeng per nummer levert. `resultat`: `orgnr, firma, navn, mobil, kilde, grad, sikkerhet, kan_sms, alternativer, merk`. Uten nummer: `ikke_funnet` med `sentralbord` og `firma_mobil`, gratis. Uten poeng: 403.

## E-post

### POST /epost/finn
`{"fornavn", "etternavn", "domene"}` eller `{"navn", "orgnr"}`. 1 berikelse. Kjent adresse (A/B) hvis personen er daglig leder; ellers domenets bekreftede mønster (C) med `alternativer`; ellers vanligste norske mønster (D).

### POST /epost/valider
`{"eposter": [≤100]}` eller `{"epost"}`. 1 per adresse. Per adresse: `syntaks, domene, domene_svarer, rolleadresse, fridomene, engangsdomene, kjent_i_datasettet, vurdering, grad`.

### GET /epost/omvendt
`?epost=` eller `?domene=`. `resultat` = selskap som over + `treff` (daglig leders adresse | selskapets domene). 1 berikelse ved treff.

## Sjekk

### POST /sjekk
`{"rader": [{id, orgnr, firma, domene, navn, epost, telefon, linkedin, tittel}, …]}` inntil 100. Selskapet finnes på orgnr, ellers domene (også fra e-postadressen hvis den ikke er gmail o.l.), ellers firmanavn.

Per rad: `treff` (person når navnet er daglig leder, selskap når bare selskapet finnes, ingen), `orgnr, firma, daglig_leder, bransje, ansatte, fylke, kommune, hjemmeside, omsetning, kundetype, sentralbord, firma_epost`, og når personen er daglig leder (eller raden ikke har navn): `epost_status` og `telefon_status` med verdiene `lik`, `avviker`, `vi_mangler`, `du_mangler`, `begge_mangler`, pluss `beste_epost`, `beste_epost_grad`, `har_mobil`, `mobil_grad`.

Ved `avviker` avslører vi ikke vårt nummer, bare at det er et annet; e-posten vår står i `beste_epost`. 1 berikelse per rad med treff. Innsendte verdier lagres som bidrag ([vilkår](/vilkar) § 6).

## MCP

HTTP: `https://firmasett.arnu.io/mcp` med samme nøkkel i `Authorization`, eller `https://firmasett.arnu.io/mcp/fs_…`. Stdio: `mcp_server.py`. Verktøyene speiler endepunktene: `sok_selskaper, berik_selskap, berik_selskaper, sok_personer, berik_person, finn_mobil, finn_epost, valider_epost, omvendt_epost, sjekk_liste, bransjer, konto, bruk`. Oppsett per klient på [MCP-sida](/slik-virker-det/mcp).

## CLI

`firmasett` dekker alle endepunkter og legger til `sjekk` og `berik-fil` for CSV, `--alle --ut` for å dumpe søk, og `skill install`. Se [CLI-sida](/slik-virker-det/cli).

## Grenser

| Plan | Berikelser | Søketreff | Vindu |
|---|---|---|---|
| Gratis | 1 000 | 100 | totalt |
| Solo | 1 000 | 500 | 5 timer, rullerende |
| Pro | 15 000 | 7 500 | 5 timer, rullerende |
| Team | 150 000 | 75 000 | 5 timer, rullerende |


Grensene deles av alle nøkler på kontoen. Konto-, bruk- og bransjeendepunktene teller aldri.

## Versjonering

Feltnavn og konvolutt er stabile i v1. Nye felt kan komme til uten varsel; felt fjernes ikke uten ny versjon.

---
Kilde: https://firmasett.arnu.io/dok · Firmasett, norsk B2B-data for folk og AI-agenter. Hele tjenesten: https://firmasett.arnu.io/llms.txt