# REST-API

> Ett API med én svarform for alt. Nøkkel i Authorization-hodet, JSON inn og ut, status i kroppen, kvote i hvert svar.


Firmasett API svarer alltid på samme måte, uansett om du søker, beriker eller validerer. Det gjør det lett å bygge mot, og lett for en agent å bruke riktig fra første forsøk.

**Base:** `https://firmasett.arnu.io/v1` · **Nøkkel:** `Authorization: Bearer fs_…` · **Format:** JSON · **Beskrivelse:** [openapi.json](/openapi.json)

## Konvolutten

```json
{"status": "ok",
 "resultat": {"…": "…"},
 "meta": {"plan": "pro", "vindu": "5 timer",
          "berikelser": {"grense": 15000, "brukt": 412, "igjen": 14588},
          "sok": {"grense": 7500, "brukt": 1200, "igjen": 6300},
          "telefonpoeng": 143, "belastet": {"berikelse": 1}}}
```

- `status` er `ok`, `ikke_funnet` eller `feil`. **Les den, ikke bare HTTP-koden.** `ikke_funnet` er HTTP 200, `resultat` er null (eller delvis, for eksempel sentralbordnummer når vi mangler mobil), og det koster ingenting.
- `meta` følger hvert svar og sier hva som er igjen og hva kallet kostet.
- Ved `feil` kommer `feil.kode` (`ugyldig_foresporsel` 400, `ugyldig_nokkel` 401, `ingen_telefonpoeng` 403, `kvote_brukt` 429) og `feil.melding` på norsk. 429 har `Retry-After`-hode i sekunder.

## Endepunkter

| Endepunkt | Gjør | Koster |
|---|---|---|
| `GET /konto` | Plan, kvoter, forbruk | gratis |
| `GET /bruk` | Forbruk per dag siste 30 dager | gratis |
| `GET /bransjer` | Næringskoder med antall og dekning, fylkene | gratis |
| `GET /selskaper/sok` | Søk selskaper med fritekst og filtre (`register=ja` søker hele Enhetsregisteret) | 1 søketreff per treff, `antall_kun=ja` gratis |
| `GET /selskaper/{orgnr}` | Alt om ett selskap | 1 berikelse |
| `POST /selskaper/berik` | `{"orgnrs": [≤100]}` | 1 per funnet |
| `GET /personer/sok` | Daglige ledere, samme filtre | 1 søketreff per treff |
| `POST /berik/person` | `{"orgnr"}` eller `{"navn", "firma" | "domene"}` | 1 berikelse |
| `POST /telefon/finn` | `{"orgnr" | "firma" | "domene"}` → mobil | 1 telefonpoeng per nummer |
| `POST /epost/finn` | `{"fornavn", "etternavn", "domene" | "orgnr"}` | 1 berikelse |
| `POST /epost/valider` | `{"eposter": [≤100]}` | 1 per adresse |
| `GET /epost/omvendt` | `?epost=` eller `?domene=` | 1 berikelse |
| `POST /sjekk` | `{"rader": [≤100 × {id, orgnr, firma, domene, navn, epost, telefon}]}` | 1 per treff |

Hvert filter til søket står i [dokumentasjonen](/dok#filtre).

## Eksempel

```bash
curl -s -X POST https://firmasett.arnu.io/v1/berik/person \
  -H "Authorization: Bearer fs_…" -H "Content-Type: application/json" \
  -d '{"navn": "Morten Aarrestad", "domene": "sandneselektriske.no"}'
```

```json
{"status": "ok",
 "resultat": {"navn": "Morten Aarrestad", "tittel": "Daglig leder", "orgnr": "810034882", "firma": "Sandnes Elektriske As",
              "epost": "morten@sandneselektriske.no", "epost_kilde": "navn i adressen", "epost_grad": "A", "epost_sikkerhet": "høy", "epost_alternativer": 1,
              "har_mobil": true, "mobil": "tilgjengelig", "mobil_grad": "A", "kan_sms": true,
              "linkedin": "", "andre_selskaper": "…"},
 "meta": {"…": "…", "belastet": {"berikelse": 1}}}
```

Mobilnummeret hentes bevisst:

```bash
curl -s -X POST https://firmasett.arnu.io/v1/telefon/finn -H "Authorization: Bearer fs_…" -H "Content-Type: application/json" -d '{"orgnr": "810034882"}'
```

## Bunker

`/selskaper/berik`, `/epost/valider` og `/sjekk` tar inntil 100 elementer. Hvert element får sin egen `status` i `resultater`, og bare treff belastes.

## Bruksområder

- **Clay, n8n, Make, Zapier:** ett HTTP-steg per endepunkt. Se [integrasjoner](/slik-virker-det/integrasjoner).
- **CRM-berikelse:** webhook ved ny kontakt → `/berik/person` → skriv tilbake e-post, grad og selskapsdata.
- **Innkommende leads:** skjema med e-post → `/epost/omvendt` → fullt selskapsbilde.
- **Egne agenter:** gi modellen [openapi.json](/openapi.json) eller [llms.txt](/llms.txt).
- **Regnskapssystemer:** kunder fra Tripletex eller Fiken → `/sjekk` → avvik i kontaktinfo.

## Grenser og rimelig bruk

Grensene gjelder per plan og per 5-timersvindu, delt av alle nøkler på kontoen. Søk har lavere grense enn berikelse fordi søk er det som brukes til masseuttrekk. [Rimelig bruk](/rimelig-bruk) forklarer hva som er greit.

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