# Urval av bolag

Lista aktiebolag efter bransch, län eller kommun, och efter antal anställda och omsättning. En sida om högst 50 bolag kostar 0,50 kr, ett tomt urval är gratis.

Källa: https://app.bolagskvarnen.se/docs/api/urval

```http
GET /api/v1/companies/screen
```

| Operation | Scope | Pris per uppslag |
| --- | --- | --- |
| `screen_companies` (urval av bolag (per sida)) | `companies:read` | 0,50 kr |

## Parametrar

| Namn | Var | Typ | Standard | Beskrivning |
| --- | --- | --- | --- | --- |
| `sni` | query | string | – | SNI-koder eller prefix på 2–5 siffror, kommaseparerade, till exempel `62` eller `62010,63`. Ett prefix träffar både huvudbransch och sekundära branscher. Högst 20 värden. |
| `region` | query | string | – | Län, kommaseparerade. Länskod 01–25 (`1` går också) eller länets namn, till exempel `Stockholm` eller `Stockholms län`. Stora och små bokstäver spelar ingen roll. Högst 50 värden. |
| `municipality` | query | string | – | Kommun, kommaseparerade. Kommunkod med fyra siffror som börjar med länskoden (`0180`) eller kommunens namn, till exempel `Göteborg` eller `Solna kommun`. Högst 50 värden. |
| `employees` | query | string | – | Antal anställda, kommaseparerade intervall: `0`, `1-4`, `5-9`, `10-19`, `20-49`, `50-99`, `100-199`, `200-499`, `500-999`, `1000-1499`, `1500-1999`, `2000-2999`, `3000-3999`, `4000-4999`, `5000-9999`, `10000-` och `Uppgift saknas`. Registrets egen form (`10-19 anställda`) går också. |
| `turnover_min` | query | integer ≥ 0 | – | Lägsta omsättning i tusen kronor (tkr), enligt senaste årsredovisning. Bolag utan årsredovisning faller bort när du anger `turnover_min` eller `turnover_max`. |
| `turnover_max` | query | integer ≥ 0 | – | Högsta omsättning i tusen kronor (tkr). Får inte vara lägre än `turnover_min`. |
| `legal_form` | query | "AB" | `AB` | Bara `AB` stöds. Urvalet omfattar bara aktiebolag. |
| `require_email` | query | boolean | `false` | `true` tar bara med bolag som har en e-postadress på huvudkontoret. |
| `exclude_ad_blocked` | query | boolean | `false` | `true` utesluter bolag där någon aktiv arbetsplats har sagt nej till reklam. |
| `limit` | query | integer 1–50 | `50` | Antal bolag på sidan. Priset är detsamma oavsett. |
| `cursor` | query | string | – | `next_cursor` från förra svaret, för nästa sida. Gäller bara med exakt samma urval; `limit` får ändras. |

Header: `Authorization: Bearer …` (krävs). `Idempotency-Key` stöds inte här och ger `400 invalid_idempotency_key`.

## Exempel

### IT-konsulter i Stockholms län, ett bolag per sida

curl:

```bash
curl -s "https://app.bolagskvarnen.se/api/v1/companies/screen?sni=62&region=Stockholm&limit=1" \
  -H "Authorization: Bearer $BOLAGSKVARNEN_KEY"
```

JavaScript:

```js
const res = await fetch('https://app.bolagskvarnen.se/api/v1/companies/screen?sni=62&region=Stockholm&limit=1', {
  headers: { Authorization: `Bearer ${process.env.BOLAGSKVARNEN_KEY}` },
})
const body = await res.json()
if (body.status !== 'ok') {
  throw new Error(`${body.error.code}: ${body.error.message}`)
}
console.log(body.data, body.meta.attribution ?? [])
```

Python:

```python
import os
import requests

res = requests.get(
    "https://app.bolagskvarnen.se/api/v1/companies/screen?sni=62&region=Stockholm&limit=1",
    headers={"Authorization": f"Bearer {os.environ['BOLAGSKVARNEN_KEY']}"},
    timeout=10,
)
body = res.json()
if body["status"] != "ok":
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"], body["meta"].get("attribution", []))
```

Svar från sandlådan (HTTP 200):

```json
{
  "status": "ok",
  "data": {
    "rows": [
      {
        "org_number": "569900-0203",
        "name": "Provkod Stockholm AB",
        "sni": {
          "code": "62010",
          "text": "Dataprogrammering"
        },
        "seat": {
          "municipality": "STOCKHOLM",
          "region": "STOCKHOLM"
        },
        "employees_interval": "5-9 anställda",
        "turnover_tsek": 6400,
        "turnover_year": 2025,
        "has_email": true,
        "ad_blocked": false
      }
    ],
    "total": 2,
    "total_capped": false,
    "next_cursor": "eyJhIjoiNTY5OTAwMDIwMyIsImgiOiJlNjRkYWQ4NTJjMjE4MTA2In0",
    "data_refreshed_at": "2026-10-26T09:30:00Z"
  },
  "meta": {
    "request_id": "d996e68c-88df-4ab3-8fb9-6286949b8830",
    "source": [
      "sandbox"
    ],
    "attribution": [
      {
        "source": "getbolag-sandbox",
        "supplier": "Bolagskvarnen",
        "notice": "Påhittad testdata. Inga riktiga bolag eller personer."
      }
    ],
    "retrieved_at": "2026-11-19T15:19:45.910Z",
    "data_updated_at": "2026-10-26T06:00:00Z",
    "cost_sek": 0,
    "environment": "test",
    "database": "Bolagskvarnen (bolagskvarnen.se)",
    "publisher": "Bolagskvarnen, ett varumärke i Bolagskällan AB (559555-5946)",
    "coverage": {
      "screen": "available"
    }
  }
}
```

### Inget urval angivet

```bash
curl -s "https://app.bolagskvarnen.se/api/v1/companies/screen?limit=10" \
  -H "Authorization: Bearer $BOLAGSKVARNEN_KEY"
```

Svar från sandlådan (HTTP 400):

```json
{
  "status": "error",
  "error": {
    "code": "filter_required",
    "message": "Ange minst ett av sni, region och municipality."
  }
}
```

## Om svaret

- Urvalet listar bara aktiva aktiebolag. Enskilda firmor, handelsbolag och avregistrerade bolag finns inte med, och inga personnummer lämnas ut.
- Minst ett av `sni`, `region` och `municipality` krävs. Flera filter kombineras med och; flera värden i samma filter med eller. Ett bolag kommer högst en gång.
- Län och kommun anges med kod eller namn. Namnen är registrets, till exempel `Stockholm` och `Göteborg`; `Stockholms län` och `Solna kommun` går också. Länskoden är 01–25, och en kommunkod börjar med sitt läns kod. `sni=62` träffar alla koder som börjar på 62, både huvudbransch och sekundära branscher.
- Varje rad har `org_number`, `name`, `sni` (huvudbransch), `seat` (kommun och län), `employees_interval`, `turnover_tsek`, `turnover_year`, `has_email` och `ad_blocked`. E-postadressen själv ingår inte: hämta den med [`detail=full`](https://app.bolagskvarnen.se/docs/api/bolag) för de bolag du vill ha.
- `turnover_tsek` är nettoomsättning i tusen kronor ur senaste årsredovisning, och `turnover_year` är året den slutade. Bolag utan årsredovisning har `null` och faller bort om du filtrerar på omsättning.
- `total` är antalet bolag i hela urvalet, som mest 1 000. Är det fler är `total_capped` `true`. Smalna av urvalet om du behöver ett exakt antal.
- Bläddra med `next_cursor`: skicka den som `cursor` med samma filter. Är `next_cursor` `null` finns inga fler sidor. Ändrar du ett filter ger cursorn `400 invalid_cursor`; `limit` får du ändra.
- **Uppgifterna kan vara upp till ungefär ett dygn gamla.** Urvalet byggs om varje dag kl. 09.30 UTC, efter registrets dagliga inläsning. `data_refreshed_at` visar när urvalet byggdes. Bolagsprofilen med `detail=full` är live.
- En sida kostar 0,50 kr oavsett om den har 1 eller 50 bolag. Ett tomt urval (`rows: []`, `total: 0`) är gratis och ger `200`, inte `404`. Varje anrop räknas mot taket på 500 urval per konto och dygn, också tomma urval. Anrop som avvisas med `400` för ogiltiga parametrar räknas inte, och inte heller anrop som föll på fel hos oss (`500`, `503`). När taket är nått blir felet `429 screen_quota_exceeded`, och `Retry-After` anger tiden till nästa dygn.
- Urvalet räknas inte mot taket för antal olika bolag per dygn, bara en bolagsprofil du hämtar efteråt gör det.
- Tar urvalet för lång tid, eller byggs det om just då, blir svaret `503 unavailable` med `Retry-After`. Det debiteras inte. Försök igen om en stund, gärna med ett smalare urval.
- Testnycklar (`gb_test_…`) ger bara sandlådans påhittade bolag och kostar inget. Ett urval som `sni=62&region=Stockholm` ger några av dem.
- `Idempotency-Key` stöds inte: urvalet har inget bolag att knyta nyckeln till, så headern ger `400 invalid_idempotency_key`. Ett tomt urval kostar ändå inget.

## Felkoder

| Kod | HTTP | Vad du gör |
| --- | --- | --- |
| `filter_required` | 400 | Lägg till en bransch, ett län eller en kommun. Kraven finns så att inte hela registret går att räkna upp. |
| `invalid_parameter` | 400 | Kontrollera parametrarna mot endpointens tabell. Okända parametrar avvisas i stället för att ignoreras. |
| `invalid_cursor` | 400 | Skicka `next_cursor` från förra svaret tillsammans med samma filter, eller börja om utan `cursor`. |
| `screen_quota_exceeded` | 429 | Vänta till nästa dygn. `Retry-After` anger sekunderna kvar. Smalna av urvalet så att färre sidor behövs. |
| `unauthorized` | 401 | Skicka `Authorization: Bearer gb_test_…` eller `gb_live_…`. Kontrollera att hela nyckeln kom med. En OAuth-token gäller en timme; förnya den med refresh-token. |
| `insufficient_scope` | 403 | Skapa en nyckel med rätt scope under Konto → Nycklar. Se [scopes](https://app.bolagskvarnen.se/docs/autentisering#scopes). |
| `email_not_verified` | 403 | Klicka på länken i bekräftelsemejlet, eller skicka ett nytt från Konto. |
| `user_disabled` | 403 | Be kontots ägare att aktivera användaren, eller använd en egen nyckel. |
| `account_not_active` | 403 | Använd en testnyckel tills kontot är godkänt. Status syns under Konto. |
| `blocked_by_phase` | 403 | Försök inte igen automatiskt. Använd en testnyckel mot sandlådan, eller kontakta support@bolagskvarnen.se om live-data. Se [sandlådan](https://app.bolagskvarnen.se/docs/sandlada). |
| `suspended` | 403 | Kontakta support@bolagskvarnen.se. |
| `rate_limited` | 429 | Vänta så många sekunder som `Retry-After` anger och försök igen. Se [takt och tak](https://app.bolagskvarnen.se/docs/takt-och-tak). |
| `insufficient_credits` | 402 | Fyll på under Konto → Krediter. |
| `monthly_cap_reached` | 402 | Höj taket under Konto, eller vänta till nästa månad. |
| `key_daily_cap_reached` | 402 | Höj nyckelns tak under Konto → Nycklar, eller vänta till nästa dygn. |
| `invalid_idempotency_key` | 400 | Skicka ett kort, unikt värde per uppslag, till exempel ett UUID. Skicka ingen `Idempotency-Key` alls till urvalet. |
| `internal_error` | 500 | Försök igen med samma `Idempotency-Key`. Ange `request_id` om du kontaktar support. |
