Berikning API

Flödesöversikt

Användare

Din tjänst

TIC Identity

1

Autentisera med BankID

2

Session complete + webhook

3

POST /api/v1/enrichment inom 30 min

4

Returnerar secureUrl

5

GET /api/v1/enrichment/data/{token} engångsåtkomst

6

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	Inkomstuppgifter (senaste 2 åren)
`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 (inkomstuppgifter för senaste 2 åren)

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`, `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", "income"]
  }'

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', 'income']
  })
});

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", "income"],
  "completedTypes": ["spar", "companyRoles", "income"],
  "secureUrl": "/api/v1/enrichment/data/f1e2d3c4-b5a6-7890-cdef-123456789abc",
  "secureUrlExpiresAtUtc": "2024-01-15T14:45:00Z"
}

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

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

Response

200 OK

{
  "personalNumber": "199001011234",
  "name": "Anna Andersson",
  "enrichedAtUtc": "2024-01-15T14:30:00Z",
  "spar": {
    "person_IdNummer": "199001011234",
    "namn_Fornamn": "Anna",
    "namn_Efternamn": "Andersson",
    "folkbokforingsadress_SvenskAdress_Utdelningsadress1": "Storgatan 1",
    "folkbokforingsadress_SvenskAdress_PostNr": "11122",
    "folkbokforingsadress_SvenskAdress_Postort": "Stockholm",
    "personDetaljer_Fodelsedatum": "1990-01-01",
    "skydd_Sekretessmarkering": false,
    "skydd_SkyddadFolkbokforing": false
  },
  "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"
    }
  ],
  "income": [
    {
      "ar_DEKL": 2024,
      "ink_TJ": 650000,
      "ink_TAX_FORV": 580000,
      "sk_SLUT": 195000
    },
    {
      "ar_DEKL": 2023,
      "ink_TJ": 620000,
      "ink_TAX_FORV": 555000,
      "sk_SLUT": 182000
    }
  ]
}

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 Statens personadressregister. Fältnamn matchar SPAR:s kolumnnamn.

Fält	Beskrivning
`person_IdNummer`	Personnummer
`namn_Fornamn`	Förnamn
`namn_Mellannamn`	Mellannamn
`namn_Efternamn`	Efternamn
`namn_Tilltalsnamn`	Tilltalsnamn
`personDetaljer_Fodelsedatum`	Födelsedatum
`personDetaljer_Kon`	Kön
`folkbokforingsadress_SvenskAdress_*`	Folkbokföringsadress
`sarskildPostadress_*`	Särskild postadress
`kontaktadress_*`	Kontaktadress
`skydd_Sekretessmarkering`	Sekretessmarkering
`skydd_SkyddadFolkbokforing`	Skyddad folkbokföring

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

Fastighetsinnehav

Ägaruppgifter från Lantmäteriet.

Fält	Beskrivning
`fastighetObjektIdentitet`	Unik fastighetsidentifierare
`registerbeteckning`	Fastighetsbeteckning (t.ex. "STOCKHOLM KUNGSHOLMEN 1:5")
`andelTaljare`	Ägarandel täljare
`andelNamnare`	Ägarandel nämnare
`ownershipStartDate`	Datum för ägarskap

Inkomstuppgifter

Inkomsttaxering från Skatteverket. Fältnamn matchar Skatteverkets kolumnnamn.

Fält	Beskrivning
`ar_DEKL`	Deklarationsår
`ink_TJ`	Inkomst av tjänst
`ink_NRV_AKT_TOT`	Aktiv näringsverksamhet totalt
`ink_NRV_PASS_TOT`	Passiv näringsverksamhet totalt
`ink_TAX_FORV`	Taxerad förvärvsinkomst
`ink_BESK_FORV`	Beskattningsbar förvärvsinkomst
`oskott_KAP`	Överskott kapital
`uskott_KAP`	Underskott 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.)
`abuseConfidenceScore`	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

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",
      "abuseConfidenceScore": 0,
      "isTor": false,
      "isLikelyVpn": false
    },
    "deviceIp": {
      "ipAddress": "94.254.120.75",
      "countryCode": "SE",
      "countryName": "Sweden",
      "isp": "Telenor Sverige AB",
      "usageType": "Mobile ISP",
      "abuseConfidenceScore": 0,
      "isTor": false,
      "isLikelyVpn": false
    },
    "risk": {
      "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

Flödesöversikt

Översikt

Flöde

Datakällor

Begär berikning

Request Body

Response

Hämta berikningsdata

Response

Datamodeller

SPAR (Folkbokföring)

Företagsengagemang

Fastighetsinnehav

Inkomstuppgifter

IP Intelligence

IP-data per adress

Riskbedömning

Riskindikatorer

Exempel på webhook med IP Intelligence

Felhantering

Säkerhet