Dokumentasjon for API

Kom i gang #

Send JSON til https://firmalisten.no/company/search. Bruk API-tokenet fra Innstillinger med Pro eller Max.

curl 'https://firmalisten.no/company/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer DITT_API_TOKEN' \
  --data '{
    "query": "rørlegger",
    "filter": { "county_code": "03" },
    "page": 1
  }'

Parametere #

Alle felt er valgfrie. {} søker uten søketekst eller filtre.

Felt	Type	Beskrivelse
`query`	string	Søketekst. Standard: `""`.
`filter`	object	Filtre kombinert med OG.
`sort`	object	Feltnavn med `"asc"` eller `"desc"`.
`page`	integer	Sidenummer fra `1`. Standard: `1`.
`limit`	integer	Kun Max: `1`–`100`. Standard: `20`. Utelates med Pro.

Søket dekker organisasjonsnummer, navn og virksomhetsbeskrivelse. Alle søkeord må matche; skrivefeil rettes ikke. Andre parametere, som fields, size og offset, ignoreres.

Filtre #

En verdi betyr likhet. En liste betyr ELLER. Ulike felt og flere operatorer på samme felt kombineres med OG.

{
  "filter": {
    "county_code": ["03", "32"],
    "type_code": "AS",
    "employees": { "gte": 5, "lte": 50 },
    "has_email": true
  }
}

Dette gir aksjeselskaper i Oslo eller Akershus med 5–50 ansatte og e-postadresse.

Operator	Betydning	Operator	Betydning
`eq`	Lik	`ne`	Ulik
`gt`	Større enn	`gte`	Større enn eller lik
`lt`	Mindre enn	`lte`	Mindre enn eller lik

Bruk strenger for koder, tall for tallfelt og true / false for boolske felt. Tomme verdilister og operatorobjekter avvises. Se filterfeltene, NACE-koder og fylkes- og kommunekoder.

Sortering #

{
  "sort": {
    "employees": "desc",
    "name": "asc"
  }
}

Feltene prioriteres i angitt rekkefølge, før tekstlig relevans. Bruk asc eller desc. Alle filterfelt unntatt roles og tags kan brukes, uavhengig av abonnement. Uten sort brukes tekstlig relevans, så relevance synkende og orgnr stigende.

Svar og paginering #

HTTP 200 med ok: true. Eksempel med ett fiktivt firma:

{
  "ok": true,
  "data": {
    "hits": [
      {
        "orgnr": "123456789",
        "name": "Eksempel Rørlegger AS",
        "industry1_name": "VVS-arbeid",
        "county_name": "Oslo",
        "website": "https://example.com",
        "registered_at": "2020-01-15T00:00:00.000Z",
        "employees": 12,
        "relevance": 100
      }
    ],
    "query": "rørlegger",
    "processing_time_ms": 2,
    "hits_per_page": 10,
    "page": 1,
    "total_pages": 1,
    "total_hits": 1
  }
}

Felt i `data`	Innhold
`hits`	Firma på siden. `[]` ved ingen treff.
`query`	Søketeksten.
`processing_time_ms`	Søkemotorens behandlingstid i ms.
`hits_per_page`	Valgt sidestørrelse.
`page`	Gjeldende sidenummer.
`total_pages`	Antall sider.
`total_hits`	Totalt antall treff.

Firmafeltene er vist i eksemplet: employees og relevance er tall, øvrige felt er strenger. Felt kan mangle eller være null. E-post og telefon returneres ikke.

Øk page med 1, og behold resten av søket. Stopp ved total_pages eller tom hits. Data kan endres mellom forespørslene.

Bruksgrenser #

Tilgang	Treff per side	Per sekund¹	Per minutt
Pro	10	1	100
Max	20, opptil 100 med `limit`	5	300

¹ Med gyldig API-token. Grensene deles per konto. Kun Max kan angi limit.

Feil #

Kontroller både HTTP-status og ok.

HTTP	Svar	Handling
`200`	`ok: false`, `message`, eventuelt `fields`	Rett parametrene eller håndter søkefeilen.
`400`	Ugyldig forespørsel	Kontroller JSON og HTTP-headere.
`429`	Teksten `Too many requests`	Vent før neste forsøk.

fields inneholder valideringsfeil per parameter. Eksempel: Pro støtter ikke filter på email.

{
  "ok": false,
  "message": "Valideringsfeil",
  "fields": {
    "filter": ["Field \"email\" is not available on your plan"]
  }
}

Søkefeil har message, uten fields. Feilsvar er ikke alltid JSON.

Filterfelt #

Pro #

Type	Felt
Boolean	`is_new`, `is_active`, `has_employees`, `has_website`, `has_email`, `has_phone`
Number	`income`, `employees`
String	`type_code`, `industry1_code`, `county_code`, `municipality_code`

Max #

Alle feltene ovenfor, pluss:

Type	Felt
Identitet	`orgnr`, `name`, `type_name`, `main_unit`, `lang`, `summary`
Forretningsadresse	`ba_street`, `ba_area_name`, `ba_area_code`, `ba_municipality_name`, `ba_municipality_code`, `ba_county_name`, `ba_county_code`, `ba_country_name`, `ba_country_code`
Postadresse	`pa_street`, `pa_area_name`, `pa_area_code`, `pa_municipality_name`, `pa_municipality_code`, `pa_county_name`, `pa_county_code`, `pa_country_name`, `pa_country_code`
Geografi	`municipality_name`, `county_name`, `country_name`, `country_code`
Bransje og sektor	`industry1_name`, `industry2_name`, `industry2_code`, `industry3_name`, `industry3_code`, `sector_name`, `sector_code`, `industry_name`, `industry_code`
Kontakt	`phone`, `mobile`, `fax`, `website`, `email`, `contact`
Number	`equity`, `expenses`, `result`, `debt`, `assets`, `accounting_year`, `last_accounting_year`, `relevance`
Boolean	`bankrupt`, `closed`, `shut`, `in_company_registry`, `in_vat_registry`, `in_foundation_registry`, `in_voluntary_registry`, `has_contact_data`, `has_accounting_data`, `has_reserved`, `reserved_mobile`, `reserved_phone`
Date	`registered_at`, `founded_at`, `last_hire_at`, `created_at`, `updated_at`
Array	`roles`, `tags`

Identitet, adresser, geografi, bransje og kontakt er tekstfelt. ba_ er forretningsadresse; pa_ er postadresse. industry1_code er primær NACE-kode. Virtuelle felt som search og counties, samt _id, kan ikke brukes som filtre.