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å 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.

Gränser & krediter

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

org_numbers är den effektivare vägen — högre gräns och 10× billigare. 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):

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
names	array	Obligatorisk	Array med företagsnamn att slå upp. Maximalt 100 namn per förfrågan. Använd antingen `names` eller `org_numbers`.
org_numbers	array	Valfri	Array med 10-siffriga organisationsnummer att slå upp. Alternativ till `names` och den effektivare vägen: högre gräns (upp till 5 000 för Starter/Pro) och 10 företag för 1 kredit. Bindestreck normaliseras automatiskt.
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"
}