Person API information model

This page provides a concise introduction to the information model used in the Person API. While the technical specification is available in the OpenAPI specification, this document offers a more human-readable overview of the data structure.

The Person API's information model is a superset of the model used by the National Population Register ("Folkeregisteret/FREG"). While maintaining the same core structure, the Person API enriches certain data points beyond FREG's base data. For details on these enrichments, see: Enrichments

For comprehensive information about FREG's information model, refer to: Folkeregisterets informasjonsmodell or the latest documentation: Informasjonsmodell v4.51

General Structure and Information Metadata

The person document consists of distinct information parts, typically provided as lists. Each list item represents a specific piece of information with associated metadata, indicating its current status (valid or historic), registration details, source information, etc.

Key metadata fields for each information item:

Metadata JSON Name FREG Name Data Type Description
isValid erGjeldende boolean Indicates whether this information is currently valid and in use
registeredAt ajourholdstidspunkt datetime Registration timestamp in FREG
source kilde string Information source (e.g., individual, UDI, hospital)
reason aarsak string Registration reason (e.g., "født i Norge" (born in Norway) or "innflyttet til Norge" (immigrated to Norway) for resident status)
validFrom gyldighetstidspunkt datetime Timestamp when the information became valid (e.g., a national identity number is valid from birth but may be registered later)
validTo opphoerstidspunkt datetime Expiration timestamp for historical information

A minified json sample from test data for a persons name with relevant metadata is given below:

{
  "name": [
    {
      "givenName": "RAKRYGGET",
      "familyName": "ABBED",
      "registeredAt": "2022-02-22T07:36:17.753116Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Patch",
      "validFrom": "2022-02-22T07:36:17.753113Z",
      "validTo": null
    }
  ]
}

A complete JSON response example is available in the JSON Response Example section below.

Common Information Parts

The Person API returns information as lists containing both current and historical data. Each list item is marked with an isValid flag to indicate whether it represents current or historical information. There are three main patterns:

  1. Single Valid Item: Some fields, like Norwegian identification numbers (NINs), must have exactly one valid item
  2. Multiple Valid Items: Fields like family relations can have multiple concurrent valid items
  3. Empty or Historical: Empty (null) fields are ignored in the response. Fields can contain only historical records.

The table below summarizes the most commonly used information parts and their characteristics:

Information Part JSON Node Name Valid Items Description
Norwegian Identification Numbers (NINs) norwegianIdentificationNumber 1 The person's current and historical identification numbers. Exactly one number must be valid at any time.
Name name 1 The person's current and historical names. Only one name can be valid at a time.
Gender gender 1 The person's gender information. Only one gender can be valid at a time.
Person Status status 1 Current status in Norway (resident, deceased, emigrated, etc). One status must be valid.
Birth birth 1 Birth information. Typically contains a single record.
Death death N/A Death information if applicable. Not a list - either contains data or is null.
Family Relations familyRelation 0-n Current and historical family relationships. Multiple relationships can be valid concurrently.
Parental Responsibility parentalResponsibility 0-n Current and historical parental responsibilities. Multiple records can be valid concurrently.
Address Protection addressProtection 0-1 The person's overall address protection level across residential, present, and shared residence addresses. Can be set to: unclassified, confidential, or strictly confidential. When no data (null), treated as unclassified.
Common Contact Register Information (KRR) commonContactRegisterInformation N/A Contact information from the Common Contact Register (KRR). Contains only current valid information without history. Either present with data or null if no information exists.

Address Information

The Person API and FREG support multiple address types for each person. The appropriate address type depends on your use case (e.g., postal communication versus determining physical residence). For detailed information about addresses, refer to chapter 5.9 in the FREG Information Model Documentation.

Available address types:

Address Type JSON Node Name Valid Items Description
Residential Address residentialAddress 0-1 Primary residential address for Norwegian citizens with a national identity number (fødselsnummer). Must match the Norwegian Property Register (Matrikkelen).
Present Address presentAddress 0-1 Temporary address for non-residents with a d-number. Limited to one valid address at a time.
Shared Residence sharedResidence 0-1 Additional residence address, typically used for children with shared custody arrangements.
Postal Address postalAddress 0-1 Alternative mailing address when regular mail should not go to the residential address.
Foreign Postal Address foreignPostalAddress 0-1 International mailing address for persons residing abroad.

Additional Information

The Person API includes other relevant information types such as:

  • Marital status
  • Citizenship
  • Additional identifiers
  • Family relationships

For comprehensive documentation of these fields, refer to the FREG Information Model.

For questions about the Person API or its information model, contact us at utvikling-persontjenesten@nhn.no.

JSON Response Example

Below is a representative JSON response from our test environment. While not exhaustive, it demonstrates typical data structures and relationships. Note that in version 3 of the API, null values are omitted from responses.

Json example 
{
  "id": "b55209b9-0be0-43c3-b1df-4d3e3cdeda63",
  "sequenceNumber": 185183,
  "norwegianIdentificationNumber": [
    {
      "status": "InUse",
      "identificationNumber": "06896496989",
      "identificationNumberType": "NationalIdentityNumber",
      "registeredAt": "2020-12-22T16:08:24.354Z",
      "isValid": true,
      "source": "KILDE_DSF"
    }
  ],
  "identityVerification": [],
  "residuaryEstateContactInformation": [],
  "identificationDocument": [],
  "status": [
    {
      "status": "Resident",
      "registeredAt": "2020-12-22T16:08:24.354Z",
      "isValid": true,
      "source": "KILDE_DSF",
      "validFrom": "2020-12-22T16:08:24.354Z"
    }
  ],
  "immigrationAuthoritiesIdentificationNumber": [],
  "foreignPersonIdentificationNumber": [],
  "sharedResidence": [],
  "gender": [
    {
      "gender": "Male",
      "isValid": true,
      "source": "KILDE_DSF"
    }
  ],
  "birth": [
    {
      "birthDate": "1964-09-06T00:00:00Z",
      "birthYear": "1964",
      "birthMunicipalityNumber": "3020",
      "birthCountry": "NOR",
      "registeredAt": "2022-02-18T13:35:07.043124Z",
      "isValid": true,
      "source": "Synutopia",
      "validFrom": "1964-09-06T13:35:07.04312Z"
    }
  ],
  "birthInNorway": [
    {
      "organizationName": "Bra Testinstitusjon",
      "multipleBirthNumber": 11,
      "registeredAt": "2022-02-18T13:35:07.13083Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Fødsel",
      "validFrom": "1964-09-06T13:35:07.13083Z"
    }
  ],
  "familyRelation": [
    {
      "relatedPerson": "26879497719",
      "relatedPersonsRole": "Child",
      "myRoleForRelatedPerson": "Father",
      "registeredAt": "2022-02-18T13:35:06.690672Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Patch",
      "validFrom": "1994-07-25T23:00:00Z"
    },
    {
      "relatedPerson": "13926298253",
      "relatedPersonsRole": "SpouseOrPartner",
      "myRoleForRelatedPerson": "SpouseOrPartner",
      "registeredAt": "2022-03-11T15:35:30.391334Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Patch",
      "validFrom": "1991-02-09T15:35:30.143021Z"
    },
    {
      "relatedPerson": "22848797212",
      "relatedPersonsRole": "Child",
      "myRoleForRelatedPerson": "Father",
      "registeredAt": "2022-02-23T14:55:25.645122Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Patch",
      "validFrom": "1987-04-21T23:00:00Z"
    },
    {
      "relatedPerson": "07893049740",
      "relatedPersonsRole": "Father",
      "myRoleForRelatedPerson": "Child",
      "registeredAt": "2022-03-11T15:35:31.290816Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Patch",
      "validFrom": "1964-09-05T23:00:00Z"
    },
    {
      "relatedPerson": "04922649486",
      "relatedPersonsRole": "Mother",
      "myRoleForRelatedPerson": "Child",
      "registeredAt": "2022-03-11T15:35:31.062102Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Patch",
      "validFrom": "1964-09-05T23:00:00Z"
    }
  ],
  "maritalStatus": [
    {
      "status": "Married",
      "statusDate": "1991-02-09T00:00:00Z",
      "authority": "DEN_NORSKE_KIRKE",
      "municipalityNumber": "0301",
      "municipalityName": "Oslo",
      "countyNumber": "03",
      "countyName": "Oslo",
      "place": "Sist Testkirke",
      "relatedByMaritalStatus": "13926298253",
      "registeredAt": "2022-03-11T15:35:30.143022Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Patch",
      "validFrom": "1991-02-09T15:35:30.143021Z"
    }
  ],
  "name": [
    {
      "givenName": "FRISK",
      "familyName": "BÅT",
      "registeredAt": "2022-02-18T13:35:07.224651Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Patch",
      "validFrom": "2022-02-18T13:35:07.224649Z"
    }
  ],
  "addressProtection": [],
  "residentialAddress": [
    {
      "streetAddress": {
        "separatelyOccupiedUnitNumber": "H0202",
        "separatelyOccupiedUnitType": "Housing",
        "addressName": "Kirkegata",
        "addressNumber": {
          "houseNumber": "19",
          "houseLetter": "B"
        },
        "addressCode": "13707",
        "city": {
          "cityName": "OSLO",
          "postalCode": "0153"
        },
        "municipalityNumber": "0301",
        "municipalityName": "Oslo",
        "countyNumber": "03",
        "countyName": "Oslo"
      },
      "cadastralIdentifier": "285856075",
      "addressConfidentiality": "Unclassified",
      "moveDate": "2022-03-11T00:00:00Z",
      "basicStatisticalUnit": 102,
      "fullBasicStatisticalUnitNumber": "03010102",
      "basicStatisticalUnitName": "Sentrum 1 - Rode 2",
      "constituency": 1601,
      "schoolDistrict": 216,
      "churchDistrict": 5,
      "urbanDistrictCode": "030104",
      "urbanDistrictName": "St.Hanshaugen",
      "geographicalUrbanDistrictCode": "030116",
      "geographicalUrbanDistrictName": "Sentrum",
      "registeredAt": "2022-03-11T15:35:33.018848Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Flytting innenlands",
      "validFrom": "2022-03-10T23:00:00Z"
    }
  ],
  "presentAddress": [
    {
      "isAddressUnknown": true,
      "addressConfidentiality": "Unclassified",
      "presentAddressDate": "2022-12-18T00:00:00Z",
      "stayElsewhere": "Military",
      "registeredAt": "2022-12-18T10:01:01.189209Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Oppholdsadresse og opphold annet sted",
      "validFrom": "2022-12-17T23:00:00Z"
    }
  ],
  "immigrationToNorway": [],
  "emigrationFromNorway": [],
  "useOfSamiLanguage": [],
  "samiParliamentElectoralRegistryStatus": [],
  "postalAddress": [
    {
      "addressConfidentiality": "Unclassified",
      "postBoxAddress": {
        "postBoxIdentification": "Test 61",
        "city": {
          "cityName": "VESTSIDA",
          "postalCode": "2863"
        }
      },
      "registeredAt": "2022-12-18T10:01:00.568046Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Oppholdsadresse og opphold annet sted",
      "validFrom": "2022-12-17T23:00:00Z"
    }
  ],
  "foreignPostalAddress": [],
  "parentalResponsibility": [],
  "citizenship": [
    {
      "countryCode": "NOR",
      "aquiredDate": "1964-09-06T00:00:00Z",
      "registeredAt": "2022-02-18T13:35:07.316077Z",
      "isValid": true,
      "source": "Synutopia",
      "reason": "Fødsel",
      "validFrom": "1964-09-06T13:35:07.316093Z"
    }
  ],
  "citizenshipRetention": [],
  "residencePermit": [],
  "stayOnSvalbard": [],
  "guardianshipOrFuturePowerOfAttorney": [],
  "legalAuthority": [],
  "commonContactRegisterInformation": {
    "reservation": "No",
    "status": "Active",
    "notificationStatus": "CanBeNotified",
    "contactInformation": {
      "email": "kjetil.braadland@capgemini.com",
      "emailLastUpdated": "2023-11-15T12:39:49+01",
      "emailLastVerified": "2023-11-15T12:39:49+01",
      "phoneNumber": "+4741522179",
      "phoneNumberLastUpdated": "2023-11-15T12:39:49+01",
      "phoneNumberLastVerified": "2023-11-15T12:39:49+01"
    },
    "digitalPost": {}
  }
}