Berikning API

Berika autentiserade sessioner med data från folkbokföring (SPAR), företagsengagemang, fastighetsinnehav och inkomstuppgifter.

Kräver konfiguration

Berikning måste aktiveras för din tenant. Kontakta support@tic.io för att konfigurera vilka datakällor du vill använda.

Användargodkännande krävs

När berikning är aktiverat visas ett samtyckemeddelande i BankID-appen under autentiseringen. Användaren måste godkänna datahämtningen innan berikning kan utföras.

Flödesöversikt

Användare

Din tjänst

TIC Identity

Autentisera med BankID

Session complete + webhook

POST .../enrichment 30 min

Returnerar secureUrl

GET .../enrichment/data/{token} 1×

Berikningsdata (JSON)

⏱ 30 min tidsgräns mellan steg 2→3 och 4→5

1× Steg 3 och 5 kan endast utföras en gång per session

Översikt

Berikning utförs på en slutförd autentiseringssession och returnerar en tidsbegränsad URL där data kan hämtas. Berikningsdata lagras krypterat och URL:en är giltig i 30 minuter.

Viktigt: Berikning måste begäras inom 30 minuter efter slutförd autentisering. Varje session kan endast berikas en gång, och data-URL:en kan endast användas en gång. Se till att hämta informationen när du behöver den och undvik att spara information som du inte behöver. Om du exempelvis behöver en folkbokföringsadress i ett flöde så hämta bara den berikade informationen när besökaren har kommit till det steget.

Flöde

Användaren startar autentisering (BankID)
BankID visar samtycketext om vilka datakällor som hämtas
Användaren godkänner och signerar
Sessionen blir complete
Du anropar berikning med sessionId (endast en gång per session)
Du får tillbaka en secureUrl (giltig 30 min, engångsåtkomst)
Du hämtar och sparar data från secureUrl

Datakällor

Typ	Källa	Beskrivning
`SPAR`	SPAR/Navet	Folkbokföringsuppgifter: namn, adress, skyddad identitet
`CompanyRoles`	Bolagsverket	Företagsengagemang, styrelseuppdrag, firmateckning
`PropertyOwnership`	Lantmäteriet	Fastighetsinnehav och ägarandelar
`Income`	Skatteverket	Inkomsttaxering: förvärvsinkomst, kapitalinkomst, slutlig skatt
`IpIntelligence`	IP-riskanalys	IP-intelligens: land, ISP, VPN/Tor-detektion, riskbedömning
`Full`	Alla	Samtliga konfigurerade datakällor

Samtycke i BankID

När berikning är aktiverat visas ett samtyckemeddelande i BankID-appen. Meddelandet genereras automatiskt baserat på de datakällor som är konfigurerade för din tenant.

Exempel på samtyckemeddelande

Visas i BankID-appen

Registerutdrag

Genom att signera begär du ett elektroniskt
registerutdrag från kreditupplysningsbolaget
The Intelligence Company AB (publ) och bekräftar
att det lämnas vidare till Ditt Företag AB.

Uppgifterna omfattar:

• SPAR (folkbokföringsuppgifter)
• Bolagsverket (bolagsengagemang)
• Lantmäteriet (fastighetsinnehav)
• Skatteverket (inkomsttaxering)

Automatiskt genererat

Samtyckemeddelandet genereras av TIC Identity baserat på din tenant-konfiguration. Endast de datakällor som är aktiverade för din tenant visas i listan. Ditt företagsnamn (DisplayName) visas som mottagare.

BankID simpleMarkdownV1

Samtyckemeddelandet använder BankID:s simpleMarkdownV1-format som stödjer rubriker, listor och enkel formatering. Detta säkerställer att meddelandet visas konsekvent i alla versioner av BankID-appen.

POST /api/v1/enrichment

Request Body

Parameter	Typ	Beskrivning
sessionId Required	guid	ID för den slutförda autentiseringssessionen
types Required	string[]	Vilka datakällor som ska hämtas: `SPAR`, `CompanyRoles`, `PropertyOwnership`, `Income`, `IpIntelligence`, `Full`
webhookUrl Optional	string	URL för webhook-notifiering när berikning är klar
state Optional	string	Godtyckligt värde som returneras i webhook

curl -X POST https://id.tic.io/api/v1/enrichment \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "types": ["SPAR", "CompanyRoles"]
  }'

const response = await fetch('https://id.tic.io/api/v1/enrichment', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sessionId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    types: ['SPAR', 'CompanyRoles']
  })
});

const result = await response.json();

Response

200 OK

{
  "enrichmentId": "f1e2d3c4-b5a6-7890-cdef-123456789abc",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "Completed",
  "requestedTypes": ["SPAR", "CompanyRoles"],
  "completedTypes": ["SPAR", "CompanyRoles"],
  "secureUrl": "/api/v1/enrichment/data/abc123securetokenxyz",
  "secureUrlExpiresAtUtc": "2024-01-15T14:45:00Z"
}

Status Values

Status	Beskrivning
`Pending`	Begäran mottagen och köad
`Processing`	Berikning pågår
`Completed`	Berikning slutförd
`PartiallyCompleted`	Delvis slutförd (vissa typer misslyckades)
`Failed`	Berikning misslyckades

GET /api/v1/enrichment/{enrichmentId}/status

curl https://id.tic.io/api/v1/enrichment/f1e2d3c4-b5a6-7890-cdef-123456789abc/status \
  -H "X-Api-Key: YOUR_API_KEY"

Response

200 OK

{
  "enrichmentId": "f1e2d3c4-b5a6-7890-cdef-123456789abc",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "Completed",
  "requestedTypes": ["SPAR", "CompanyRoles"],
  "completedTypes": ["SPAR", "CompanyRoles"],
  "secureUrl": "/api/v1/enrichment/data/abc123securetokenxyz",
  "secureUrlExpiresAtUtc": "2024-01-15T14:45:00Z"
}

GET /api/v1/enrichment/types

curl https://id.tic.io/api/v1/enrichment/types \
  -H "X-Api-Key: YOUR_API_KEY"

Response

200 OK

{
  "types": [
    { "type": "SPAR", "description": "Population register data (name, address) from SPAR/Navet", "enabled": true },
    { "type": "CompanyRoles", "description": "Board positions and company roles from Bolagsverket", "enabled": true },
    { "type": "PropertyOwnership", "description": "Property ownership from Lantmäteriet", "enabled": false },
    { "type": "Income", "description": "Income taxation data from Skatteverket", "enabled": false },
    { "type": "IpIntelligence", "description": "IP risk assessment and geolocation", "enabled": true },
    { "type": "Full", "description": "All available enrichment types", "enabled": true }
  ]
}

GET /api/v1/enrichment/data/{token}

# OBS: Ingen API-nyckel behövs - token ger åtkomst
curl https://id.tic.io/api/v1/enrichment/data/abc123securetokenxyz

Response

200 OK

{
  "personalNumber": "199001011234",
  "name": "Anna Andersson",
  "enrichedAtUtc": "2024-01-15T14:30:00Z",
  "spar": {
    "Person_IdNummer": "199001011234",
    "Person_PersonIdTyp": "PERSONNR",
    "Skydd_Sekretessmarkering": false,
    "Skydd_SkyddadFolkbokforing": false,
    "Namn_Fornamn": "Anna Maria",
    "Namn_Efternamn": "Andersson",
    "Namn_Tilltalsnamn": "Anna",
    "PersonDetaljer_Kon": "K",
    "PersonDetaljer_Fodelsedatum": "1990-01-01",
    "Folkbokforing_FolkbokfordLanKod": "01",
    "Folkbokforing_FolkbokfordKommunKod": "0180",
    "Folkbokforingsadress_SvenskAdress_Utdelningsadress1": "Storgatan 1",
    "Folkbokforingsadress_SvenskAdress_PostNr": "11122",
    "Folkbokforingsadress_SvenskAdress_Postort": "Stockholm"
  },
  "companyRoles": [
    {
      "companyId": 12345,
      "companyRegistrationNumber": "5566778899",
      "legalName": "Exempel AB",
      "legalEntityType": "AB",
      "positionTypes": ["VD", "LED"],
      "positionDescriptions": ["Verkställande direktör", "Styrelseledamot"],
      "positionStart": "2020-01-15",
      "positionEnd": null,
      "companyStatus": "Aktivt",
      "signatureDescription": "Styrelsen eller verkställande direktören",
      "signingAuthorityAnalysis": {
        "summary": "Firman tecknas av styrelsen eller verkställande direktören var för sig.",
        "rules": [
          {
            "description": "Styrelsen",
            "type": "board",
            "requiredSignatories": null,
            "requiredRoles": ["LE", "OF"]
          },
          {
            "description": "Verkställande direktören ensam",
            "type": "alone",
            "requiredSignatories": 1,
            "requiredRoles": ["VD"]
          }
        ],
        "eligiblePersons": [
          {
            "personId": 42,
            "personalIdentityNumber": "198001011234",
            "name": "Anna Svensson",
            "roles": ["Verkställande direktör", "Styrelseledamot"],
            "canSignAlone": true,
            "applicableRules": ["Verkställande direktören ensam"]
          }
        ]
      }
    }
  ],
  "propertyOwnerships": [
    {
      "fastighetObjektIdentitet": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "registerbeteckning": "STOCKHOLM NORRMALM 1:1",
      "andelTaljare": 1,
      "andelNamnare": 1,
      "ownershipStartDate": "2019-08-20"
    }
  ],
  "income": [
    {
      "AR_DEKL": 2023,
      "INK_TJ": 650000,
      "INK_TAX_FORV": 650000,
      "INK_BESK_FORV": 580000,
      "OSKOTT_KAP": 15000,
      "SK_SLUT": 195000
    }
  ]
}

Engångsåtkomst

URL:en kan endast användas en gång. Efter att data har hämtats blir URL:en ogiltig. Se till att spara datan direkt vid hämtning.

Datamodeller

SPAR (Folkbokföring)

Data från folkbokföringen via SPAR/Navet. Fältnamnen matchar SPAR:s kolumnnamn.

Personidentifikation

Fält	Beskrivning
`Person_IdNummer`	Personnummer
`Person_PersonIdTyp`	Typ av ID (PERSONNR, SAMORDNINGSNR)
`Person_SenasteAndringSPAR`	Senaste ändring i SPAR

Skyddsflaggor

Fält	Beskrivning
`Skydd_Sekretessmarkering`	Har sekretessmarkering
`Skydd_SkyddadFolkbokforing`	Har skyddad folkbokföring
`PersonDetaljer_Sekretessmarkering`	Persondetalj-sekretess

Namnuppgifter

Fält	Beskrivning
`Namn_Fornamn`	Förnamn
`Namn_Mellannamn`	Mellannamn
`Namn_Efternamn`	Efternamn
`Namn_Aviseringsnamn`	Aviseringsnamn
`Namn_Tilltalsnamn`	Tilltalsnamn

Persondetaljer

Fält	Beskrivning
`PersonDetaljer_Kon`	Kön (M/K)
`PersonDetaljer_Fodelsedatum`	Födelsedatum
`PersonDetaljer_Avlidendatum`	Avlidendatum (om avliden)
`PersonDetaljer_Avregistreringsdatum`	Avregistreringsdatum
`PersonDetaljer_AvregistreringsorsakKod`	Orsak till avregistrering (kod)
`PersonDetaljer_AvregistreringsorsakBeskrivning`	Orsak till avregistrering

Folkbokföringsadress

Fält	Beskrivning
`Folkbokforing_FolkbokfordLanKod`	Länskod
`Folkbokforing_FolkbokfordKommunKod`	Kommunkod
`Folkbokforing_DistriktKod`	Distriktkod
`Folkbokforing_Folkbokforingsdatum`	Folkbokföringsdatum
`Folkbokforingsadress_SvenskAdress_CareOf`	c/o-adress
`Folkbokforingsadress_SvenskAdress_Utdelningsadress1`	Gatuadress rad 1
`Folkbokforingsadress_SvenskAdress_Utdelningsadress2`	Gatuadress rad 2
`Folkbokforingsadress_SvenskAdress_PostNr`	Postnummer
`Folkbokforingsadress_SvenskAdress_Postort`	Postort

Skyddad identitet

Om personen har sekretessmarkering eller skyddad folkbokföring returneras endast skyddsflaggorna, någon annan information finns inte tillgänglig.

Företagsengagemang

Styrelseuppdrag och roller från Bolagsverket.

Fält	Beskrivning
`companyId`	Internt företags-ID
`companyRegistrationNumber`	Organisationsnummer
`legalName`	Företagsnamn
`legalEntityType`	Bolagsform (AB, HB, etc.)
`positionTypes`	Positionskoder (VD, LED, etc.)
`positionDescriptions`	Positionsbeskrivningar
`positionStart`	Startdatum för position
`positionEnd`	Slutdatum (null = pågående)
`companyStatus`	Företagsstatus
`signatureDescription`	Firmateckningsrätt
`signingAuthorityAnalysis`	AI-genererad analys av firmateckningsrätt (se nedan)

AI-genererat innehåll

signingAuthorityAnalysis genereras av AI och kan innehålla felaktigheter. Verifiera alltid resultatet mot den ursprungliga signatureDescription innan du fattar beslut baserat på analysen. Använd analysen som ett stöd, inte som en auktoritativ källa.

PropertyOwnership (Fastighetsinnehav)

Ägaruppgifter från Lantmäteriet. Fältnamnen matchar Lantmäteriets datamodell.

Fält	Beskrivning
`fastighetObjektIdentitet`	Fastighets-ID (GUID)
`registerbeteckning`	Fastighetsbeteckning (t.ex. "STOCKHOLM KUNGSHOLMEN 1:5")
`andelTaljare`	Ägarandel täljare (t.ex. 1 för 1/2)
`andelNamnare`	Ägarandel nämnare (t.ex. 2 för 1/2)
`ownershipStartDate`	Datum när ägandet startade

Income (Inkomsttaxering)

Inkomstuppgifter från Skatteverket. Fältnamnen matchar Skatteverkets kolumnnamn.

Fält	Beskrivning
`AR_DEKL`	Deklarationsår
`INK_TJ`	Förvärvsinkomst (tjänst)
`INK_NRV_AKT_TOT`	Aktiv näringsverksamhet, totalt
`INK_NRV_PASS_TOT`	Passiv näringsverksamhet, totalt
`USK_NRV_AKT_TOT`	Underskott aktiv näringsverksamhet
`USK_NRV_PASS_TOT`	Underskott passiv näringsverksamhet
`AVDR_SALLM`	Allmänt avdrag
`INK_TAX_FORV`	Taxerad förvärvsinkomst
`INK_BESK_FORV`	Beskattningsbar förvärvsinkomst
`OSKOTT_KAP`	Överskott av kapital
`USKOTT_KAP`	Underskott av kapital
`SK_SLUT`	Slutlig skatt

IP Intelligence

IP-berikning ger insikter om de IP-adresser som använts vid autentiseringen. Två IP-adresser analyseras: klientens IP (som initierade sessionen) och enhetens IP (där BankID-appen kördes).

Automatiskt i webhooks

När IP-berikning är aktiverad inkluderas ipIntelligence automatiskt i webhook-payloaden för auth.completed och sign.completed-händelser.

IP-data per adress

Fält	Beskrivning
`ipAddress`	IP-adressen som kontrollerats
`countryCode`	Landskod (ISO 3166-1 alpha-2)
`countryName`	Landsnamn
`isp`	Internetleverantör
`usageType`	Användningstyp (ISP, Mobile, Hosting, etc.)
`confidenceScore`	Missbrukspoäng 0-100 (högre = mer rapporterad)
`isTor`	Om IP:n är en känd Tor-utgångsnod
`isLikelyVpn`	Om IP:n troligen är VPN/proxy/datacenter

Riskbedömning (`overallRisk`)

Fält	Beskrivning
`level`	Risknivå: `low`, `moderate`, `high`
`score`	Riskpoäng 0-100
`indicators`	Lista med riskindikatorer som identifierats

Riskindikatorer

Indikator	Beskrivning	Poängpåverkan
Hög missbrukspoäng	IP rapporterad för missbruk (50+)	+poäng
Tor-utgångsnod	IP är en känd Tor-nod	+40
VPN/Proxy/Hosting	IP tillhör datacenter eller VPN	+20
Nyligen rapporterad	IP har rapporterats senaste veckan	+15
Icke-nordiskt land	IP utanför SE/NO/DK/FI/IS	+10

Exempel på webhook med IP Intelligence

{
  "event": "auth.completed",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user": {
    "personalNumber": "199001011234",
    "givenName": "Anna",
    "surname": "Andersson"
  },
  "ipIntelligence": {
    "initiatingIp": {
      "ipAddress": "85.24.100.50",
      "countryCode": "SE",
      "countryName": "Sweden",
      "isp": "Telia Company AB",
      "usageType": "ISP",
      "confidenceScore": 0,
      "isTor": false,
      "isLikelyVpn": false
    },
    "deviceIp": {
      "ipAddress": "94.254.120.75",
      "countryCode": "SE",
      "countryName": "Sweden",
      "isp": "Telenor Sverige AB",
      "usageType": "Mobile ISP",
      "confidenceScore": 0,
      "isTor": false,
      "isLikelyVpn": false
    },
    "overallRisk": {
      "level": "low",
      "score": 0,
      "indicators": []
    },
    "enrichedAtUtc": "2024-01-15T14:30:00Z"
  }
}

QR-kod och olika IP-adresser

Vid QR-kodsflödet är det normalt att initiatingIp och deviceIp skiljer sig. Användaren kan starta på sin laptop (WiFi) och signera på sin mobil (4G). Detta är förväntat beteende och flaggas inte som risk automatiskt.

Felhantering

Status	Fel	Beskrivning
`400`	Enrichment not enabled for tenant	Berikning är inte aktiverat för din tenant
`400`	No valid enrichment types requested	Ingen av de begärda typerna är konfigurerade
`400`	Session not found	Sessionen hittades inte
`400`	Session not completed	Sessionen är inte slutförd
`400`	Session too old for enrichment	Sessionen är för gammal (berikning måste begäras inom 30 minuter efter slutförd autentisering)
`400`	No personal number in session	Sessionen saknar personnummer
`400`	Session has already been enriched	Sessionen har redan berikats (endast en berikning per session tillåts)
`410`	Token expired or invalid	URL:en har gått ut, redan använts, eller är ogiltig

Säkerhet

Berikningsdata hanteras med flera säkerhetslager:

Krypterad lagring: All berikningsdata krypteras med AES-256 innan den lagras
Tidsgräns för begäran: Berikning måste begäras inom 30 minuter efter slutförd autentisering
En berikning per session: Varje session kan endast berikas en gång
Engångsåtkomst: Data-URL:en kan endast användas en gång, sedan invalideras den
Tidsbegränsad URL: URL:er är giltiga i max 30 minuter
API-nyckel krävs: Alla anrop måste autentiseras
TLS: All kommunikation sker över HTTPS
Ingen data i URL:er: Känslig data skickas aldrig i query-parametrar eller redirects

Berikning API

Flödesöversikt

Översikt

Flöde

Datakällor

Begär berikning

Request Body

Response

Status Values

Hämta berikningsstatus

Response

Lista tillgängliga berikningstyper

Response

Hämta berikningsdata

Response

Datamodeller

SPAR (Folkbokföring)

Personidentifikation

Skyddsflaggor

Namnuppgifter

Persondetaljer

Folkbokföringsadress

Företagsengagemang

PropertyOwnership (Fastighetsinnehav)

Income (Inkomsttaxering)

IP Intelligence

IP-data per adress

Riskbedömning (`overallRisk`)

Riskindikatorer

Exempel på webhook med IP Intelligence

Felhantering

Säkerhet

Berikning API

Flödesöversikt

Översikt

Flöde

Datakällor

Samtycke i BankID

Exempel på samtyckemeddelande

Visas i BankID-appen

BankID simpleMarkdownV1

Begär berikning

Request Body

Response

Status Values

Hämta berikningsstatus

Response

Lista tillgängliga berikningstyper

Response

Hämta berikningsdata

Response

Datamodeller

SPAR (Folkbokföring)

Personidentifikation

Skyddsflaggor

Namnuppgifter

Persondetaljer

Folkbokföringsadress

Företagsengagemang

PropertyOwnership (Fastighetsinnehav)

Income (Inkomsttaxering)

IP Intelligence

IP-data per adress

Riskbedömning (overallRisk)

Riskindikatorer

Exempel på webhook med IP Intelligence

Felhantering

Säkerhet

Riskbedömning (`overallRisk`)