Person API information model
The intention of this page is to give a brief introduction to the information model used in the Person API. The technical specification of the information model is also provided as part of the OpenAPI specification, but this specification lacks a more human readable overview of the data we send from the Person API.
The information model in the Person API is a "superset" of the information model used by the National Population Register ("Folkeregisteret/FREG"). The main structure of the information model is identical, but the Person API enriches some additional data points on top of the data coming from FREG. See more information on which data is enriched in the Person API here: Enrichments For more detailed information on the information model used by FREG, we refer to this page: Folkeregisterets informasjonsmodell. A direct link to the latest documentation at the time of writing is: Informasjonsmodell v4.4
General structure and information metadata
The person document stored in the Person API consists of a set of separate information parts. Most information parts in FREG and the Person API are provided as lists, and each item in the list represent an individual piece of information. Each piece of information includes a set of relevant metadata, for instance indicating if the information is currently in use or if it's historic, when it was registered, which source provided the information, etc.
A description of all metadata on each piece of information is given below:
| Metadata json name | FREG name | Data type | Description |
|---|---|---|---|
| isValid | erGjeldende | boolean | Boolean flag indicating if this piece of information is the currently valid information which is in use. |
| registeredAt | ajourholdstidspunkt | datetime | When the information was registered in FREG. |
| source | kilde | string | The source that registered the information, for instance the individual himself, UDI, a hospital, etc. |
| reason | aarsak | string | The reason for registering the information. For instance, a norwegian resident can have "født i Norge" (born in norway) or "innflyttet til Norge" (immigrated to Norway) set as a reason for the "resident" person status. |
| validFrom | gyldighetstidspunkt | datetime | The time indicating when the information became currently valid. For instance a national identity number (fødselsnummer) assigned at birth will be valid from birth, but might be registered later in FREG. |
| validTo | opphoerstidspunkt | datetime | The time indicating when a piece of information is no longer valid / expired. Only used on historic information which has not been replaced by new, currently valid 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 full json sample for a response from the Person API is provided at the bottom of the page, see full json sample.
Most used information parts
As mentioned in the previous section, most information parts are provided as lists, where some items in the list
are marked as currently valid information, and other entries represent historic information.
In some cases, for instance for norwegian identification numbers (NINs),
there should only be one single item which is marked as the currently valid NIN. In other cases, like for
family relations, there will be multiple items which represent information that is currently valid. In many cases
an information part can also be empty (or null), or only contain historic information.
Below is an overview over the most commonly used information parts in the person document together with a brief description.
| Information part | Json node name | Number of currently valid (isValid) items | Description |
|---|---|---|---|
| Norwegian identification numbers (NINs) | norwegianIdentificationNumber | 1 | The persons norwegian identification number, including historic numbers. There should only be one identification number currently valid (isValid) at any given time. |
| Name | name | 1 | The persons name, including historic names. Only one name is expected to be currently valid and in use. |
| Gender | gender | 1 | The persons gender. Only one gender is expected to be currently valid and in use. |
| Person status | status | 1 | The persons status in relation to Norway, for instance if the person is a resident, deceased, emigrated etc. Only one status is expected to be currently valid and in use. |
| Birth | birth | 1 | Information on the persons birth. There should in most cases only be one item provided in this list. |
| Death | death | Not a list, is either present or null |
Information on the persons death (date of death). This data point is not a list, and is either provided if the person is registered dead, or null in all other cases. |
| Family relations | familyRelation | 0-n | The persons family relations. A family relation is usually a NIN reference to another person in the registry, but it's also possible to reference a person not in the registry. |
| Parental responsibility | parentalResponsibility | 0-n | The persons parental responsibilities. Similar to family relations this is usually a NIN reference to another person in the registry, but it's also possible to reference a person not in the registry. |
| Address protection | addressProtection | 0-1 | The persons overall address protection level, across the persons residential, present, and shared residence addresses. Can be set to unclassified, confidential or strictly confidential. No data (null) is the same as unclassified. |
| Common contact register information (KRR) | commonContactRegisterInformation | Not a list, is either present or null |
The persons contact information registered in the common contact register (KRR). Only includes the currently valid information and no history. Can be null if no information is found in the common contact register. |
Addresses
FREG and the Person API contains multiple different types of addresses that can be registered for a person. Which address to use depends on the use-case, for instance depending if you want to send a letter or if you want to determine where a person physically resides. We recommend reading chapter 5.9 in the FREG information model documentation regarding addresses: Informasjonsmodell v4.4.
FREG and the Person API offer these information parts for addresses:
| Information part | Json node name | Number of currently valid (isValid) items | Description |
|---|---|---|---|
| Residential address | residentialAddress | 0-1 | The persons residential address, including historic addresses. A norwegian citizen with a national identity number (fødselsnummer) should have a registered resident address. A residential address is matched against the norwegian property register (Matrikkelen) and will always be an official address. |
| Present address | presentAddress | 0-1 | The persons present address, including historic addresses. A person who is not yet a resident and currently has a d-number can have a present address registered. A person can at most have one currently valid present address. |
| Shared residence | sharedResidence | 0-1 | The persons shared residence address, including historic addresses. A child with citizenship and a national identity number can have registered shared residence address. |
| Postal address | postalAddress | 0-1 | The persons postal address, including historic addresses. Usually used when a person rarely resides on the registered residential address and would like to receive mail on a separate postal address. |
| Foreign postal address | foreignPostalAddress | 0-1 | The persons foreign postal address, including historic addresses. Usually used when a person resides abroad over longer periods of time and would like to receive mail on an address in another country. |
Other information parts
FREG and the Person API also contain additional information parts that can be relevant for you as a consumer, for instance information on a persons marital status, citizenship, and so on. These are not described in detail on this page, but are documented by FREG.
For any additional questions on the Person API or it's information model, send us an e-mail at utvikling-persontjenesten@nhn.no.
Full json sample
Below is a full json sample for a person in our test environment. The sample does not include data in every available information part, but serves as a "standard" example of how a response from the Person API will look for a person in the test population.
Json example
{
"id": "ac0ec3d0-b003-4584-958d-5583d5538d93",
"sequenceNumber": 11684434,
"falseIdentity": null,
"norwegianIdentificationNumber": [
{
"status": "InUse",
"identificationNumber": "06896496989",
"identificationNumberType": "NationalIdentityNumber",
"registeredAt": "2020-12-22T16:08:24.354Z",
"isValid": true,
"source": "KILDE_DSF",
"reason": null,
"validFrom": null,
"validTo": null
}
],
"identityVerification": [],
"residuaryEstateContactInformation": [],
"identificationDocument": [],
"status": [
{
"status": "Resident",
"registeredAt": "2020-12-22T16:08:24.354Z",
"isValid": true,
"source": "KILDE_DSF",
"reason": null,
"validFrom": "2020-12-22T16:08:24.354Z",
"validTo": null
}
],
"immigrationAuthoritiesIdentificationNumber": [],
"foreignPersonIdentificationNumber": [],
"sharedResidence": [],
"gender": [
{
"gender": "Male",
"registeredAt": null,
"isValid": true,
"source": "KILDE_DSF",
"reason": null,
"validFrom": null,
"validTo": null
}
],
"birth": [
{
"birthDate": "1964-09-06T00:00:00Z",
"birthYear": "1964",
"birthPlace": null,
"birthMunicipalityNumber": "3020",
"birthMunicipalityName": "Nordre Follo",
"birthCountyNumber": "30",
"birthCountyName": "Viken",
"birthCountry": "NOR",
"registeredAt": "2022-02-18T13:35:07.043124Z",
"isValid": true,
"source": "Synutopia",
"reason": null,
"validFrom": "1964-09-06T13:35:07.04312Z",
"validTo": null
}
],
"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",
"validTo": null
}
],
"familyRelation": [
{
"relatedPerson": "26879497719",
"relatedPersonWithoutIdentifier": null,
"relatedPersonsRole": "Child",
"myRoleForRelatedPerson": "Father",
"registeredAt": "2022-02-18T13:35:06.690672Z",
"isValid": true,
"source": "Synutopia",
"reason": "Patch",
"validFrom": "1994-07-25T23:00:00Z",
"validTo": null
},
{
"relatedPerson": "13926298253",
"relatedPersonWithoutIdentifier": null,
"relatedPersonsRole": "SpouseOrPartner",
"myRoleForRelatedPerson": "SpouseOrPartner",
"registeredAt": "2022-03-11T15:35:30.391334Z",
"isValid": true,
"source": "Synutopia",
"reason": "Patch",
"validFrom": "1991-02-09T15:35:30.143021Z",
"validTo": null
},
{
"relatedPerson": "22848797212",
"relatedPersonWithoutIdentifier": null,
"relatedPersonsRole": "Child",
"myRoleForRelatedPerson": "Father",
"registeredAt": "2022-02-23T14:55:25.645122Z",
"isValid": true,
"source": "Synutopia",
"reason": "Patch",
"validFrom": "1987-04-21T23:00:00Z",
"validTo": null
},
{
"relatedPerson": "07893049740",
"relatedPersonWithoutIdentifier": null,
"relatedPersonsRole": "Father",
"myRoleForRelatedPerson": "Child",
"registeredAt": "2022-03-11T15:35:31.290816Z",
"isValid": true,
"source": "Synutopia",
"reason": "Patch",
"validFrom": "1964-09-05T23:00:00Z",
"validTo": null
},
{
"relatedPerson": "04922649486",
"relatedPersonWithoutIdentifier": null,
"relatedPersonsRole": "Mother",
"myRoleForRelatedPerson": "Child",
"registeredAt": "2022-03-11T15:35:31.062102Z",
"isValid": true,
"source": "Synutopia",
"reason": "Patch",
"validFrom": "1964-09-05T23:00:00Z",
"validTo": null
}
],
"maritalStatus": [
{
"status": "Married",
"statusDate": "1991-02-09T00:00:00Z",
"authority": "DEN_NORSKE_KIRKE",
"municipalityNumber": "0301",
"municipalityName": "Oslo",
"countyNumber": "03",
"countyName": "Oslo",
"place": "Sist Testkirke",
"abroad": null,
"relatedByMaritalStatus": "13926298253",
"registeredAt": "2022-03-11T15:35:30.143022Z",
"isValid": true,
"source": "Synutopia",
"reason": "Patch",
"validFrom": "1991-02-09T15:35:30.143021Z",
"validTo": null
}
],
"death": null,
"name": [
{
"givenName": "FRISK",
"middleName": null,
"familyName": "BÅT",
"shortName": null,
"originalName": null,
"registeredAt": "2022-02-18T13:35:07.224651Z",
"isValid": true,
"source": "Synutopia",
"reason": "Patch",
"validFrom": "2022-02-18T13:35:07.224649Z",
"validTo": null
}
],
"addressProtection": [],
"residentialAddress": [
{
"streetAddress": {
"separatelyOccupiedUnitNumber": "H0202",
"separatelyOccupiedUnitType": "Housing",
"addressName": "Kirkegata",
"addressNumber": {
"houseNumber": "19",
"houseLetter": "B"
},
"addressCode": "13707",
"addressAdditionalName": null,
"city": {
"cityName": "OSLO",
"postalCode": "0153"
},
"coAddressName": null,
"municipalityNumber": "0301",
"municipalityName": "Oslo",
"countyNumber": "03",
"countyName": "Oslo"
},
"cadastralAddress": null,
"unknownResidence": null,
"cadastralIdentifier": "285856075",
"closeCadastralIdentifier": null,
"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",
"validTo": null
}
],
"presentAddress": [
{
"foreignAddress": null,
"isAddressUnknown": true,
"streetAddress": null,
"cadastralAddress": null,
"cadastralIdentifier": null,
"addressConfidentiality": "Unclassified",
"presentAddressDate": "2022-12-18T00:00:00Z",
"stayElsewhere": "Military",
"urbanDistrictCode": null,
"urbanDistrictName": null,
"geographicalUrbanDistrictCode": null,
"geographicalUrbanDistrictName": null,
"basicStatisticalUnit": null,
"fullBasicStatisticalUnitNumber": null,
"basicStatisticalUnitName": null,
"registeredAt": "2022-12-18T10:01:01.189209Z",
"isValid": true,
"source": "Synutopia",
"reason": "Oppholdsadresse og opphold annet sted",
"validFrom": "2022-12-17T23:00:00Z",
"validTo": null
}
],
"immigrationToNorway": [],
"emigrationFromNorway": [],
"useOfSamiLanguage": [],
"samiParliamentElectoralRegistryStatus": [],
"preferredContactAddress": [],
"postalAddress": [
{
"addressConfidentiality": "Unclassified",
"postBoxAddress": {
"postBoxOwner": null,
"postBoxIdentification": "Test 61",
"city": {
"cityName": "VESTSIDA",
"postalCode": "2863"
}
},
"streetAddress": null,
"freeFormPostalAddress": null,
"cadastralIdentifier": null,
"registeredAt": "2022-12-18T10:01:00.568046Z",
"isValid": true,
"source": "Synutopia",
"reason": "Oppholdsadresse og opphold annet sted",
"validFrom": "2022-12-17T23:00:00Z",
"validTo": null
}
],
"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",
"validTo": null
}
],
"citizenshipRetention": [],
"residencePermit": [],
"stayOnSvalbard": [],
"guardianshipOrFuturePowerOfAttorney": [],
"deprivedLegalAuthority": [],
"legalAuthority": [],
"commonContactRegisterInformation": {
"reservation": "No",
"status": "Active",
"notificationStatus": "CanBeNotified",
"contactInformation": {
"email": "email@provider.com",
"emailLastUpdated": "2023-11-15T12:39:49+01",
"emailLastVerified": "2023-11-15T12:39:49+01",
"phoneNumber": "+4712345678",
"phoneNumberLastUpdated": "2023-11-15T12:39:49+01",
"phoneNumberLastVerified": "2023-11-15T12:39:49+01"
},
"digitalPost": {
"digitalPostAddress": null,
"digitalPostVendorAddress": null
},
"certificate": null,
"language": null,
"languageLastUpdated": null
}
}