Alternate Identification Number API

Alternativ identifikasjonsnummer‑API (AIN‑API) brukes til å reservere og oppdatere nasjonale alternative identifikasjonsnumre (AIN‑er), også kjent som felles nasjonale hjelpenumre i den norske helsesektoren.

Formålet med AIN‑API er å støtte sikker, sporbar og standardisert håndtering av felles nasjonale hjelpenumre når en fysisk person ikke kan identifiseres med et norsk identifikasjonsnummer (NIN: personnummer eller D‑nummer), eller når det er usikkert om personen har et slikt nummer. Et AIN skal kun benyttes når det er nødvendig å utføre oppgaver som helsetjenesten eller helse‑ og omsorgsadministrasjonen er pålagt ved lov eller forskrift.

Typiske eksempler er turister, utenlandske arbeidere og beredskapssituasjoner der personen ikke kan identifiseres med et NIN på tidspunktet helsesektoren trenger å identifisere vedkommende.

Konsumenter kan reservere AIN‑er og oppdatere den støttede personinformasjonen som er registrert på dem. AIN‑er og tilhørende data er tilgjengelige for oppslag og søk i Person‑API.

Gi tilbakemeldinger og spørsmål til utvikling-persontjenesten@nhn.no

Formål og tillatt bruk

Bruk AIN‑API kun når alle følgende betingelser er oppfylt:

• Personen kan ikke identifiseres med et NIN, eller det er ukjent om personen har ett.
• AIN er nødvendig for å løse en oppgave i helsetjenesten eller i helse‑ og omsorgsadministrasjonen.
• Oppgaven er påkrevd av lov eller forskrift.

AIN kan også brukes i beredskapssituasjoner når de samme betingelsene gjelder.

AIN skal ikke brukes til:

• Anonymisering eller pseudonymisering.
• Å lage et alias for et kjent NIN.
• Å lage en duplikat‑identifikator for en person som allerede er trygt identifisert.
• Testing i produksjon.
• Modellering av familierelasjoner eller andre administrative relasjoner som ligger utenfor API‑ens formål.
• Håndtering av fosterprøver, forskning eller andre spesialiserte arbeidsflyter som krever andre valideringsregler, med mindre bruken er juridisk vurdert og eksplisitt inkludert i avtalen med NHN.

Tallserien er begrenset. Konsumenter må unngå unødvendige reserveringer og må ikke teste opprettelse av AIN i produksjon. NHN kan følge opp bruken, og tilgang kan fjernes dersom API‑en brukes utenfor det dokumenterte formålet eller konsumentens avtale.

Informasjon som kan registreres på et AIN

Følgende opplysninger kan registreres sammen med et AIN:

• Navn
• Kjønn
• Fødselsdato
• Nåværende adresse

Registrer kun den informasjonen som er nødvendig for å identifisere personen i den aktuelle helsetjenesteoppgaven. Et AIN er en felles nasjonal identifikator, ikke et konsument‑eiet register. Alle autoriserte konsumenter med skrivetilgang kan oppdatere støttede opplysninger på et eksisterende AIN, og oppdateringer er synlige via Person‑API.

API‑en støtter for øyeblikket ikke personstatus, AIN‑status, landinformasjon, familierelasjoner eller en kobling mellom et AIN og et NIN. Hvis en person allerede er identifisert med et NIN, skal dette nummeret brukes i stedet for å opprette eller oppdatere et AIN som alias.

Adresseinformasjon

Adresseinformasjon som registreres gjennom AIN‑API blir eksponert som PresentAddress i Person‑API. Adresse‑modellen følger Person‑API‑ens og Folkeregisterets strukturer for nåværende adresse der dette er relevant.

Adresse‑validering fungerer per i dag slik:

• Postnummer valideres som fire sifre.
• Gateadresse valideres ikke mot et offisielt gateadresseregister.
• Stedsnavn (city) returneres som en del av adresse‑dataene når det er tilgjengelig, men konsumenter bør ikke stole på en egen valideringsregel for stedsnavn med mindre dette er dokumentert i OpenAPI‑spesifikasjonen.
• Landinformasjon støttes ikke.

Spesifikasjon for alternativ identifikasjonsnummer

Den alternative identifikasjonsnummer‑serien har OID (Object Identifier) 2.16.578.1.12.4.1.4.3.

Et AIN består av to deler. Den første delen er et ni‑sifret tall fra den konfigurerte serien for miljøet. Siffer 10 og 11 er kontrollsiffer, beregnet på samme måte som for norske identifikasjonsnumre. Nummeret inneholder ingen ytterligere informasjon, som fødselsdato eller kjønn, og skal kun brukes til identifikasjon.

For en oversikt over OID‑serier som er i bruk i helsesektoren, se: OID‑identifikatorserier for helse‑ og omsorgstjenester

Alternative identifikasjonsnumre i Person‑API

Reserverte AIN‑er er tilgjengelige for oppslag og søk i Person‑API. Eksisterende eldre AIN‑er fra den tidligere PREG‑nummer‑serien er også fortsatt tilgjengelige for oppslag og søk i Person‑API. get-by-nin‑endepunktet kan brukes direkte med et AIN for å hente informasjonen som er registrert på nummeret. Søke‑endepunkter inkluderer AIN‑resultater kun når parametrene IncludeAINs eller IncludeAINResults er satt.

I Person‑API blir selve AIN‑et representert i NorwegianIdentificationNumber med identificationNumberType satt til AlternateIdentificationNumber. Kun følgende deler av Person‑API‑ens respons bør forventes for en person registrert med et AIN:

• NorwegianIdentificationNumber
• Birth
• Gender
• Name
• PresentAddress

{
  "id": "ed608abe-bfe6-4a16-a062-bb3553f0ad4e",
  "sequenceNumber": 12408795,
  "falseIdentity": null,
  "norwegianIdentificationNumber": [
    {
      "status": "InUse",
      "identificationNumber": "80500066532",
      "identificationNumberType": "AlternateIdentificationNumber",
      "registeredAt": null,
      "isValid": true,
      "source": null,
      "reason": null,
      "validFrom": null,
      "validTo": null
    }
  ],
  "identityVerification": [],
  "residuaryEstateContactInformation": [],
  "identificationDocument": [],
  "status": [],
  "immigrationAuthoritiesIdentificationNumber": [],
  "foreignPersonIdentificationNumber": [],
  "sharedResidence": [],
  "gender": [
    {
      "gender": "Female",
      "registeredAt": null,
      "isValid": true,
      "source": null,
      "reason": null,
      "validFrom": null,
      "validTo": null
    }
  ],
  "birth": [
    {
      "birthDate": "1992-11-25T00:00:00Z",
      "birthYear": null,
      "birthPlace": null,
      "birthMunicipalityNumber": null,
      "birthMunicipalityName": null,
      "birthCountyNumber": null,
      "birthCountyName": null,
      "birthCountry": null,
      "registeredAt": null,
      "isValid": true,
      "source": null,
      "reason": null,
      "validFrom": null,
      "validTo": null
    }
  ],
  "birthInNorway": [],
  "familyRelation": [],
  "maritalStatus": [],
  "death": null,
  "name": [
    {
      "givenName": "Uendelig",
      "middleName": "Lyspære",
      "familyName": "Trombone",
      "shortName": null,
      "originalName": null,
      "registeredAt": null,
      "isValid": true,
      "source": null,
      "reason": null,
      "validFrom": null,
      "validTo": null
    }
  ],
  "addressProtection": [],
  "residentialAddress": [],
  "presentAddress": [
    {
      "foreignAddress": null,
      "isAddressUnknown": null,
      "streetAddress": {
        "separatelyOccupiedUnitNumber": null,
        "separatelyOccupiedUnitType": null,
        "addressName": "Klovne Bilens veg 76 B",
        "addressNumber": null,
        "addressCode": null,
        "addressAdditionalName": null,
        "city": {
          "cityName": null,
          "postalCode": "7053"
        },
        "coAddressName": null,
        "municipalityNumber": "5001",
        "municipalityName": "Trondheim - Tråante",
        "countyNumber": "50",
        "countyName": "Trøndelag - Trööndelage"
      },
      "coordinate": {
        "epsgCode": 25833,
        "north": 7273600,
        "east": 454000
      },
      "cadastralAddress": null,
      "cadastralIdentifier": null,
      "addressConfidentiality": "Unclassified",
      "presentAddressDate": null,
      "stayElsewhere": null,
      "urbanDistrictCode": null,
      "urbanDistrictName": null,
      "geographicalUrbanDistrictCode": null,
      "geographicalUrbanDistrictName": null,
      "basicStatisticalUnit": null,
      "fullBasicStatisticalUnitNumber": null,
      "basicStatisticalUnitName": null,
      "registeredAt": null,
      "isValid": true,
      "source": null,
      "reason": null,
      "validFrom": null,
      "validTo": null
    }
  ],
  "immigrationToNorway": [],
  "emigrationFromNorway": [],
  "useOfSamiLanguage": [],
  "samiParliamentElectoralRegistryStatus": [],
  "postalAddress": [],
  "foreignPostalAddress": [],
  "parentalResponsibility": [],
  "citizenship": [],
  "citizenshipRetention": [],
  "residencePermit": [],
  "stayOnSvalbard": [],
  "guardianshipOrFuturePowerOfAttorney": [],
  "legalAuthority": [],
  "commonContactRegisterInformation": null
}

Nummerserie i bruk

Seriene med tilgjengelige tall for reservering er forhåndsgenerert i hvert miljø. Produksjons‑serien er begrenset, så produksjonsnumre skal kun reserveres for reell produksjonsbruk.

Nye AIN‑reserveringer bruker følgende intervaller:

Legacy‑AIN‑er fra den tidligere PREG‑nummer‑serien finnes fortsatt i API‑en. Disse tallene bruker følgende intervaller i AIN‑API:

Valideringsfeil

Noen eldre alternative identifikasjonsnumre fra den tidligere PREG‑serien kan feile på den nåværende kontrolldigits‑valideringen. Disse numrene kan ikke endres. Kontakt NHN dersom du er usikker på om et eksisterende nummer er gyldig for bruk.

OpenAPI‑spesifikasjon

Se Alternate Identification Number API

Versjonering

Se Versjonering

Autentisering og autorisasjon

Dette API‑et bruker HelseID for autentisering og autorisasjon. For å bruke API‑et trenger du et gyldig HelseID‑token med et gyldig scope. Tilgjengelig scope for Alternativ identifikasjonsnummer‑API er: nhn:persontjenesten-felles-hjelpenummer/tilgang-dpop.

API-et er tilgjengelig for konsumenter av Persontjenesten Person‑API med et gyldig tjenestetilbud og en avtale.