POST/v1/bulk

Bulkuppslag

Slå upp flera företag i en enda förfrågan.

Översikt

Bulkuppslag-endpointen låter dig slå upp flera företag på organisationsnummer eller namn i en enda API-förfrågan. Detta är mer effektivt än att göra flera individuella förfrågningar när du behöver slå upp flera företag samtidigt. Organisationsnummer är det snabbare och mer kostnadseffektiva valet, särskilt för stora batcher.

Gränser & krediter

Uppslag	Max per förfrågan	Kreditkostnad
`org_numbers`	500 (Free) / 5 000 (Starter & Pro)	10 företag för 1 kredit (rundas uppåt)
`names`	100 per förfrågan	1 kredit per lyckad matchning

org_numbers är den effektivare vägen — högre gräns, 10× billigare och betydligt snabbare. En batch med 5 000 organisationsnummer returnerar på bara några sekunder, medan names-uppslag arbetar betydligt långsammare. Misslyckade uppslag debiteras aldrig.

Fuzzy-matchning

API:et returnerar alltid närmaste match. Bedöm kvaliteten via score: 1.0 = exakt, > 0.8 = mycket god, < 0.6 = tveksam (verifiera manuellt).

Förfrågan

Förfrågningskropp

Skicka ett JSON-objekt med en array av företagsnamn:

json

{
  "names": ["Spotify AB", "Ericsson AB", "Skanska AB"]
}

Eller en array av organisationsnummer i stället. Det är den effektivare vägen (högre gräns, 10 företag för 1 kredit, och betydligt snabbare: tusentals nummer på några sekunder):

json

{
  "org_numbers": ["5567037485", "5560042001", "5564831114"]
}

Ange names eller org_numbers

Använd antingen names eller org_numbers i samma förfrågan. Skickar du en tom kropp ({}) returneras 400 med felet Missing or invalid "names" array - det är backendens standardvalidering, men org_numbers är ett fullt giltigt alternativ (se exemplet ovan).

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
org_numbers	array	Antingen/eller	Array med 10-siffriga organisationsnummer att slå upp. Den effektivare vägen: högre gräns (upp till 5 000 för Starter/Pro), 10 företag för 1 kredit och betydligt snabbare. Bindestreck normaliseras automatiskt. Ange antingen `org_numbers` eller `names` — minst en av dem krävs.
names	array	Antingen/eller	Array med företagsnamn att slå upp. Maximalt 100 namn per förfrågan. Ange antingen `names` eller `org_numbers` — minst en av dem krävs.
has_annual_report	boolean	Valfri	Filtrera namnuppslag på årsredovisning. `true` = enbart företag med digital årsredovisning, `false` = enbart företag utan. Utelämnas parametern filtreras inte (alla företag matchas). Gäller endast `names`-uppslag.
include	string[]	Valfri	Opt-in-väljare för berikad data. Stödjer för närvarande `"trademarks"`, som lägger till fälten `trademarks` och `trademarkCount` per matchat företag. Fungerar för uppslag både på `names` och `org_numbers`. Okända värden ignoreras.
response_fields	string	Valfri	Begränsar vilka fält som returneras per företag (`minimal`, `core`). Projektionen tillämpas endast på `org_numbers`-uppslag. För `names`-uppslag och för `/v1/search` ignoreras parametern och hela företagsobjektet returneras.

Lägg till include för att berika svaret med varumärkesdata:

json

{
  "names": ["Spotify AB", "Ericsson AB"],
  "include": ["trademarks"]
}

Varumärkesdata överlever response_fields

"include": ["trademarks"] berikar varje matchat företag med fälten trademarks och trademarkCount (PRV-data). När response_fields-projektion används (endast på org_numbers-vägen, se parametern nedan) behålls dessa två fält i alla lägen, även minimal och core. Utan include saknas varumärkesfälten helt. Företag utan registrerade varumärken får [] respektive 0.

Kodexempel

Här är exempel på flera programmeringsspråk:

curl

curl -X POST 'https://data.foretagsapi.se/v1/bulk' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"names": ["Spotify AB", "Ericsson AB", "Skanska AB"]}'

Svar

Lyckat svar (200 OK)

Returnerar ett JSON-objekt som innehåller en results-array med lyckat/misslyckat-status för varje uppslag:

json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71{
  "results": [
    {
      "searchTerm": "Spotify AB",
      "success": true,
      "company": {
        "id": 521294,
        "name": "Spotify AB",
        "orgNumber": "5567037485",
        "legalForm": "AB",
        "postalAddress": {
          "street": "Regeringsgatan 19",
          "city": "STOCKHOLM",
          "postalCode": "11153"
        },
        "registrationDate": "2006-05-10",
        "score": 1.0,
        "hasDigitalAnnualReport": false,
        "financials": null,
        "revenue_estimate": {
          "value": 10000000000,
          "type": "interval",
          "interval_low": 10000000000,
          "interval_high": null,
          "reference_year": 2025,
          "source": "scb",
          "scb_class": "fin_21",
          "label_sv": "≥ 10 mdkr"
        },
        "employees_estimate": {
          "value": 1100,
          "type": "interval",
          "interval_low": 1000,
          "interval_high": 1499,
          "source": "scb",
          "scb_class": "anst_10",
          "label_sv": "1 000–1 499 anställda"
        }
      }
    },
    {
      "searchTerm": "Ericsson AB",
      "success": true,
      "company": {
        "id": 123456,
        "name": "Telefonaktiebolaget LM Ericsson",
        "orgNumber": "5560000000",
        "legalForm": "AB",
        "score": 0.85
      }
    },
    {
      "searchTerm": "Unknown Company XYZ",
      "success": true,
      "company": {
        "id": 789012,
        "name": "XYZ Company AB",
        "orgNumber": "5560001234",
        "legalForm": "AB",
        "score": 0.51
      }
    }
  ],
  "metadata": {
    "totalSearches": 3,
    "successfulSearches": 3,
    "processingTimeMs": 150,
    "timestamp": "2024-01-15T10:35:00Z",
    "mode": "api"
  }
}

Svarsfält

Fält	Typ	Beskrivning
results	array	Array med resultatobjekt, ett för varje begärt namn
results[].searchTerm	string	Den ursprungliga söktermen från förfrågan
results[].success	boolean	Om en matchning hittades (alltid true med fuzzy-matchning)
results[].company	object	Företagsdata med närmaste matchning. Kontrollera score-fältet för matchningskvalitet.
results[].company.score	number	Matchningspoäng 0.0-1.0. Lågt värde (<0.6) indikerar osäker matchning.
results[].error	string	Felmeddelande (endast närvarande om success är false, sällsynt med fuzzy-matchning)
metadata.totalSearches	number	Totalt antal företagsnamn som begärdes i batchen
metadata.successfulSearches	number	Antal uppslag som returnerade ett matchande företag
metadata.processingTimeMs	number	Behandlingstid i millisekunder
metadata.timestamp	string	Tidsstämpel för förfrågan (ISO 8601-format)

Hantera osäkra matchningar

Med fuzzy-matchning returneras alltid närmaste match. Kontrollera alltidscore-fältet för varje resultat. Vid låga poäng (<0.6) bör du verifiera matchningen manuellt eller flagga den för granskning.

Finansiell data i bulkuppslag

Fälten financials, hasDigitalAnnualReport, revenue_estimate och employees_estimate ingår i svaret för varje matchat företag. Att financials är null betyder inte att företaget saknar omsättning. Oftast har företaget lämnat in sin årsredovisning på papper i stället för digitalt, och då har vi ingen åtkomst till siffrorna. Finansiell data finns för cirka 60 % av aktiva aktiebolag som lämnat in digital årsredovisning. SCB-intervall ger storleksindikation för ytterligare bolag, totalt cirka 85 %.

revenue_estimate och employees_estimate är källmedvetna envelope-objekt: type: "exact" = värdet kommer från årsredovisningen, type: "interval" = SCB-baserat storleksintervall med interval_low/interval_high och en svensk etikett i label_sv, type: "none" = ingen storleksuppgift. Se /docs/api/search-by-name för fullständig fältlista och envelope-shape. Saknas all finansiell data returneras "financials": null och "hasDigitalAnnualReport": false.

Felsvar

400 Bad Request

Returneras när förfrågan överskrider batchgränsen:

json

{
  "error": "Too many companies. Maximum allowed: 100. Received: 101"
}

Eller när kroppen saknar både names och org_numbers (en tom kropp valideras mot names):

json

{
  "error": "Missing or invalid \"names\" array"
}