Alternate Identification Number API

The Alternate Identification Number API is an API for reserving national alternate identification numbers, that can be used for persons that can't be identified with a norwegian identification number (fødsels- eller d-nummer). This includes non-norwegian citizens or other cases where a person can't be identified.

A consumer can reserve and update basic personal information on alternate identification numbers (AINs) using the API. The following personal information can be registered together with an AIN: name, gender, date of birth and basic address information. Alternate identification numbers and related data will also be available for lookup and search in the Person API.

This API will take over for the PREG HL7 API for alternate identification numbers offered as part of Personregisteret (PREG). Numbers from both the existing PREG API and the new API will be available in the Person API until the PREG API is discontinued. Please note, numbers reserved in this API are only in PERSON API and not in PREG.

Send feedback and questions to utvikling-persontjenesten@nhn.no

Alternate identification number specification

The alternate identification number series have the OID (Object identifier) 2.16.578.1.12.4.1.4.3.

Alternate identification numbers consist of two parts. The first part is a nine digit number between 800.000.000 and 999.999.999. Digits 10 and 11 are control numbers, which are calculated the same way as for national identification numbers. The number carries no additional information such as date of birth or gender, and should only be used for identification.

For an overview of OID number series used in the health sector, see more information in norwegian here: Identifikatorserier i helse og omsorgstjenesten (ehelse.no)

Alternate identification numbers in the Person API

As mentioned above, all reserved alternate identification numbers from both the existing PREG API and the new AIN API will be available for lookup and search in the Person API. The get-by-nin endpoint can be used directly with alternate identification numbers to look up the information registered on this number. Information parts in the Person API for a person registered with an alternate identification number are:

NorwegianIdentificationNumber
Birth
Gender
Name
PresentAddress

Json example AIN person in Person API

{
  "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"
      },
      "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": [],
  "preferredContactAddress": [],
  "postalAddress": [],
  "foreignPostalAddress": [],
  "parentalResponsibility": [],
  "citizenship": [],
  "citizenshipRetention": [],
  "residencePermit": [],
  "stayOnSvalbard": [],
  "guardianshipOrFuturePowerOfAttorney": [],
  "deprivedLegalAuthority": [],
  "legalAuthority": [],
  "commonContactRegisterInformation": null
}

Number ranges in use

The range of available numbers for reservation are pre-generated in each environment, this includes numbers available in the existing PREG API.

In test environments, the following number ranges are in use:

Environment	Number range (first nine digits)
PREG test	800.000.000 - 803.999.999
AIN API test	720.000.000 - 799.999.999

In production environments, the following number ranges are in use:

Environment	Number range (first nine digits)
PREG production	800.000.000 - 803.999.999
AIN API production	805.000.000 -

OpenAPI specification

See Alternate Identification Number API

Versioning

See Versioning

Changelog

See Changelog

Authentication and authorization

This API uses HelseID for authentication and authorization. To use the API you will need to have a valid HelseID token with a valid scope. Currently there is only one scope available to consume resources from the Alternate Identification Number API: nhn:persontjenesten-felles-hjelpenummer/tilgang. This scope provides read access to information in the authorization bundle "public with legal basis" (aka statutory authority).