TINFO består av et REST API med en tilhørende testklient. Testklienten benytter REST APIet. 

Pilottjenesten inneholder i seg selv ingen teknisk kobling mellom innlogging med BankID og etterfølgende oppslag på privatadresse og telefonnummer som tilleggsinformasjon. Det forutsettes at pilotbrukersteder gjør en innlogging med BankID i eget system før pilottjenesten kalles. Pilotbrukerstedene forutsettes å benytte følgende data fra BankID-innloggingen som input til pilottjenesten:

• Mobilnummer (for BankID på mobil)
• Navn (fra CommonName i BankID-sertifikatet)
• Fødselsdato (fra BankID-sertifikatet)

Det forutsettes at pilotbrukerstedene viser en consent-screen til sluttbruker ala "Aksepterer du at din privatadresse og ditt telefonnummer utleveres fra BankID til <BRUKERSTED>?" 

Se etterfølgende avsnitt for en nærmere beskrivelse av pilottjenesten:

Tilganger

Pilottjenesten er tilgjengelig i ulike miljøer og benytter basic auth for tilgang. Kontakt developer@bankidnorge.no for forespørsel om tilgang.   

En demo i form av en implementasjon som først gjør en innlogging med BankID før pilottjenesten kalles er åpent tilgjengelig.

Merk: Alle miljøer virker mot produksjonsmiljøet til 1881.

Datagrunnlaget hos 1881

Datagrunnlaget for 1881 er bestemmende for i hvilken grad pilottjenesten vil klare å finne privatadresse og telefonnummer på en vilkårlig sluttbruker.

Databasen hos 1881 har mange inputkilder, der nattlige oppdateringer av abonnementsdata fra teleoperatørene utgjør grunnstammen. Brukere som har reservert seg mot katalogoppføringer vil fortsatt oversendes fra teleoperatørene til 1881, men markeres som reservert hos 1881.

For ca. 90% av abonnementene er brukeren kjent og det finnes fødselsdato på brukeren. Brukeren på et abonnement kalles "person" hos 1881. For privatabonnementer sammenfaller dette i all hovedsak med juridisk eier. For bedriftsabonnementer finnes det et "company" hos 1881 som utgjør juridisk eier. Blant bedriftsabonnementene er det mange hvor brukeren ikke er kjent, dvs. at det ikke finnes noen "person" hos 1881. 

Hos 1881 finnes det ca 5 millioner innslag på "person" og ca 2 mill innslag på "company".  For et vilkårlig telefonnr kan man derfor regne ca. 70% som nedre grense for treffprosent på privatadresse. Faktisk treffprosent fra pilottjenesten vil imidlertid være høyere fordi tjenesten gjør også andre søk enn oppslag på telefonnummer (se mer info under). F.eks. vil tjenesten gi treff på privatadresse en sluttbruker har (ett eller flere) privatabonnement i tillegg til et bedriftsabonnement. Hva som er faktisk treffprosent fra pilottjenesten i praktisk er pt. ukjent, og er derfor et viktig punkt å avklare gjennom pilotperioden. 

REST API

APIet består av kun ett endepunkt med 3 parametere (Telefonnummer, Fullt navn, Fødselsdato DDMMYY) der enten telefonnummer eller fullt navn må være satt. Se nærmere beskrivelse av søkealgoritme under.

Oppbygging av søk

[baseurl]/api1881/search?number=<number>&commonname=<commonname>&birthdate=<DDMMYY>

CommonName-format

APIet forventer angivelse av fullt navn slik dette er angitt i CommonName-feltet i et BankID sertifikat. Følgende formater støttes, der førstnevnte er gjeldende navnestandard i BankID:

• Etternavn, Fornavn Mellomnavn
• Etternavn,Fornavn Mellomnavn
• Etternavn; Fornavn Mellomnavn
• Etternavn;Fornavn Mellomnavn
• Fornavn Mellomnavn Etternavn

Det er antatt at etternavn kun består av ett ord.

Mulig respons fra API

{
  "statusMessage": "Status Melding (String)",
  "statusCode": "Status Code (int)", 
  "personContactInfo": {
    "firstName": "String",
    "middleName": "String",
    "lastName": "String",
    "birthDate": "String med format {YYYY-MM-DD}",
    "streetName": "String",
    "houseNumber": "String",
    "houseLetter": "String",
    "postalCode": "String",
    "postalArea": "String",
    "numbers": ["String liste"]
  },
  "companyContactInfo": {
    "companyName": "String",
    "streetName": "String",
    "houseNumber": "String",
    "houseLetter": "String",
    "postalCode": "String",
    "postalArea": "String",
    "contactName": "String",
    "contactValue": "String"
  }
}

Eksempler på søk

Et resultat som stammer fra persontreff hos 1881, vil returneres i "personContactInfo" feltet, og et resultat som stammer fra companytreff hos 1881 vil returneres i "companyContactInfo" feltet.

Eksempel på søk med person treff

url: https://preview.bankidapis.no/tinfo/api1881/search?number=90898943&commonname=Ole%20Hansen&birthdate=060150

Respons:

{
  "statusMessage": "One person hit",
  "statusCode": 1,
  "personContactInfo": {
    "firstName": "Ole",
    "middleName": null,
    "lastName": "Hansen",
    "birthDate": "1950-01-06T",
    "streetName": "Furusethveien",
    "houseNumber": "35",
    "houseLetter": null,
    "postalCode": "1811",
    "postalArea": "Askim",
    "numbers": [
      "90898943"
    ]
  },
  "companyContactInfo": null
}

Eksempel på søk med company treff

url: https://preview.bankidapis.no/tinfo/api1881/search?number=90823120

Respons:

{
  "statusMessage": "One company hit",
  "statusCode": 2,
  "personContactInfo": null,
  "companyContactInfo": {
    "companyName": "Kantega AS",
    "streetName": "Kirkegata",
    "houseNumber": "5",
    "houseLetter": null,
    "postalCode": "0153",
    "postalArea": "Oslo",
    "contactName": "Geir Ottar Kvernstuen",
    "contactValue": "90823120"
  }
}

Ekstra informasjon for "numbers" under "personContactInfo"

Ved persontreff fra 1881 er det mulig å få tilbake opptil flere telefonnummer, da både til mobil og fasttelefon. I disse tilfellene definerer 1881 hvilket nummer de tror er hovednummeret. Da det er umulig å vite om dette stemmer eller ikke har vi valgt i pilottjenesten å returnere alle nummer som kommer fra 1881 som en liste, hvor nummeret 1881 har definert som hovednummer alltid vil være øverst i denne listen.

Pilottjenesten returnerer aldri informasjon som er blitt angitt som input uten at informasjonen også har blitt returnert fra 1881. Det kan derfor forekomme at et nummer det er blitt søk på ikke vil forekomme i listen over nummer som returneres. Dette forekommer for eksempel i tilfeller hvor nummeret det er blitt søkt på er reservert, men adressen til søkt person finnes hos 1881. I disse tilfellene er det opp til brukeren av pilottjenesten å vurdere om et nummer er gyldig og om det skal brukes eller ikke.

Statuskoder og Statusmeldinger

Foreløpig implementert:

NO_HITS = "No hits for search";
NO_HITS_CODE = -1;
MORE_THAN_ONE_HIT = "More than one hit for search";
MORE_THAN_ONE_HIT_CODE = -2;
NUMBER_RESERVED = "Number listing is declined by customer request";
NUMBER_RESERVED_CODE = -3;
ONE_PERSON_HIT = "One person hit";
ONE_PERSON_HIT_CODE = 1;
ONE_COMPANY_HIT = "One company hit";
ONE_COMPANY_HIT_CODE = 2;

Søkealgoritme

Tre input  [Telefonnummer, Fult navn, Fødselsdato DDMMÅÅ], der alle kan være satt eller blanke.

Søket mot 1881 blir gjort som følger:

1. Ved gyldig telefonnummer (8 siffer) blir det gjort et primærsøk på nummeret mot 1881. 
   • Dette søket gjelder både mot privat og bedrift hos 1881.
   • Dersom det returneres ett unikt persontreff fra 1881, returneres dette og søket er fullført.
   • Dersom det returneres ett unikt bedriftstreff fra 1881, blir dette spart til senere.
2. Dersom det finnes et gyldig etternavn i common name og punkt 1 ikke traff en unik person, så starter et sekundærsøk som kan bestå av ett eller flere steg.
   1. Ved gyldig fødselsdato, blir det gjort et sekundær søk mot 1881 med common name som input og etternavn og fødselsdato som filter. Filtrering på oppgitt etternavn og fødselsdato skjer hos 1881 slik at kun relevante treff returneres. Deretter kjører pilottjenesten følgende lokale filtrering på søkeresultatet fra 1881: 
      • Filtrerer lokalt bort alle personer som har ulikt førstenavn i fornavnet som det som er blitt søkt på. For eksempel i navnet Ola Martin Nordmann, vil alle navn som ikke starter på Ola bli filtrert bort.
      • Dersom det er ett unikt persontreff etter lokal filtrering så blir dette returnert og søket er fullført.
   2. Ved gyldig fødselsdato og 2a ga mer enn 1 treff etter lokal filtrering, blir det gjort et nytt søk mot 1881 uten fødselsdato. Dette søket blir gjort for å finne eventuelle oppføringer som ikke har registrert fødselsdato. Deretter kjører pilottjenesten følgende lokale filtrering på søkeresultatet fra 1881: 
      • Filtrerer lokalt bort alle med ulikt førstenavn i fornavnet, likt som 2a, filtrerer deretter bort alle personer som har en definert fødselsdato.
      • Dersom det er ett unikt persontreff etter lokal filtrering blir dette returnert og søket er fullført.
   3. Dersom ingen av de overstående søkene fikk ett unik treff, blir det til slutt gjort ett søk mot 1881 med kun common name.
      • Filtrerer lokalt bort alle personer som returneres fra 1881 som har ulikt fornavn og eventuelt mellomnavn som det som er blitt søkt på. For eksempel i navnet Ola Martin Nordmann, vil alle navn som ikke starter på Ola Martin bli filtrert bort.
      • Dersom det er ett unikt persontreff etter filtrering igjen så blir dette returnert og søket er fullført.
      • Dersom det er ingen treff igjen etter filtrering, blir det forsøkt en lik filtrering som i 2a og 2b.
      • Dersom det er ett unikt persontreff etter filtrering igjen så blir dette returnert og søket er fullført.
3. Dersom primærsøk fikk et unikt bedrifttreff og sekundærsøket ikke fant en unik person, blir bedrifttreffet returnert.

Logging

Alle søk blir logget med formatet: 

{dato};{klokkeslett};{søktNummer};{søktCommonName};{søktFødselsDato};{fantperson:boolean};{fantFirma:boolean};{fleireTreffPåSøk:boolean};{resultatAvSøk}

Loggingen vil utelukkende bli benytter for statistikkformål for å kunne trekke nærmere konklusjoner om pilottjenestens treffprosent mot 1881.