Search in Person API
This document explains the main endpoints of search in Person API, the validation rules that every request must satisfy, and how results are ordered
- /search/person – Single‑call search
- /search/paged-match-list – Bulk search with pagination
- /search/match-count - Total count og matches returned
- event/filtered - Filtered event
/search/person – Single‑call search
Performs a one‑off query and returns the first 100 distinct person documents that match the supplied criteria. The endpoint does not support pagination; if more than 100 persons match, only the first 100 are returned.
Minimum requirements for a request
Name field – at least one of the following must be present: GivenName, MiddleName, FamilyName, or FullName.
Two letters total – when all name fields are concatenated, the string must contain at least two alphabetic characters (whitespace is ignored).
Additional filter – one of the following must also be supplied:
- BirthDate (at least the year)
- MunicipalityNumber (exactly four digits)
- PostalCode (exactly four digits)
- StreetAddress containing at least three letters (whitespace ignored) These rules prevent overly broad searches and keep the load on the database reasonable.
Parameters
| Field | Description |
|---|---|
| BirthDate | Person’s birth date, ISO 8601 format YYYY‑MM‑DD. Year‑only YYYY or year‑and‑month YYYY-MM are also accepted. |
| Gender | Person’s gender (Female/Male) |
| FullName | Whole or parts of the person’s full name, letters only, up to 600 characters. The string is split into a maximum of three search words; each word must contain at least one letter and the combined words must contain at least two letters. Rest of the search words is dismissed |
| GivenName, MiddleName, FamilyName | Part of the respective name component, letters only, up to 200 characters. |
| StreetAddress | Street name together with house number/letter, up to 200 characters. |
| PostalCode | Postal code – exactly four digits. |
| CityName | City name, letters only, up to 100 characters. This is the same in norwegian as "poststed" |
| MunicipalityNumber | Municipality number – exactly four digits. |
| Optional flags | InformationParts, IncludeAINs, IncludeHistory – control which sections of the person document are included. IncludeAINs mean get person with a alternate indetification number. |
Result
The response contains the complete person document, i.e., all personal data (including sensitive fields). Only the first 100 matches are returned, ordered by the internal database identifier (the natural order of rows). No further sorting options are available.
/search/paged-match-list – Bulk search with pagination
When large result sets are needed, /paged-match-list returns only the unique Person IDs together with pagination indexes (startIndex and endIndex). The caller can request additional pages by adjusting the offset. Person IDs are an internal person reference generated by Persontjenesten.
Pagination
PageSize – maximum number of IDs returned in a single call. The default is 1 000, the hard limit is 10 000. IndexOffset – the zero‑based start position in the overall result set. For the first request omit it or set it to 0. After each response, set the next IndexOffset to endIndex + 1. When the number of IDs in the response is smaller than PageSize, the end of the total result set has been reached.
Ordering
Results are stably sorted by the internal DB ID. This keeps pagination consistent even if records are inserted, updated, or deleted while the client is paging through the data.
Acceptable search criteria
There is no requirement to use search parameters here. Everything can be empty. But all name and address fields that exist on /search can be used here, plus a few extra filters that are only available for bulk searches:
Parameters
| Field | Description |
|---|---|
| BirthDateFrom / BirthDateTo | Inclusive range for birth date (ISO format; year‑only or year‑month are allowed). |
| DeathDateFrom / DeathDateTo | Inclusive range for date of death (same format as birth date). |
| BasicStatisticalUnit | The full basic statistical unit number of the basic statistical unit the person lives in. If provided, needs to be exactly eight digits. |
| PersonStatuses | Array of strings describing the person’s relationship to Norway/National Population Registry. |
| PageSize / IndexOffset | Controls pagination (see above). |
The same “two‑letter” and “at least one name field” rules apply, but the fields are optional provided the overall minimum requirements (name + one additional filter) are fulfilled.
Result
The JSON payload includes only the list of PersonId values together with startIndex and endIndex. No personal details are exposed. The results can be used to look up ids through /person/bulk-by-id.
/search/match-count - Total count og matches returned
Works same way as "paged-match-list" regarding search parameters, but returned result is just the total count of matches that would have been returned. Use it to predict how many matches a search with search/paged-match-list endpoint would have returned without fetching full set of data.
/event/filtered - Filtered event
Get a filtered list of events for persons matching advanced search parameters. Returns up to 1000 event documents starting from the specified sequence number, filtered by event type and person attributes such as name, address, municipality, birth/death date, gender, and person status.
Parameters
| Field | Description |
|---|---|
| SequenceNumber | The lowest sequence number that should be included in the result. Starts on 1. |
| EventTypes | Which event types that should be included in the result. Supports comma separated values. |
| IncludeAinResults | IncludeAINResults mean get person with a alternate indetification number. |
| Maxlimit | Maximum number of events to return. Default value is 1000 . |
Full-Text Search on FullName
Full‑Text Search tokenises the string and matches a prefix anywhere inside a token. Consequently the term “bo” also matches “dagbok” or “bodil”.
Specification’s demand
- Each search word must match only the beginning of a name part (first name, middle name, family name, or any component of a compound name).
- Words may appear in any order.
- A maximum of three words is used; each word must contain at least one letter, and the combined words must contain at least two letters.
Search on special characters
The names stored in the search tables are normalised. For example every variant of the letter “u” (e.g. ù, ú, û, ü, ũ, ū, ŭ, ů, ű, ų, ư, ǔ, ǖ, ǘ, ǚ, ǜ, ȕ, ȗ, ʉ, ᵤ, ᶙ, ṳ, ṵ, ṷ, ṹ, ṻ, ụ, ủ, ứ, ừ, ử, ữ, ự, ｕ) is converted to a single, standard “u.” Consequently, the presence or type of diacritical marks on letters in a search query does not affect the lookup – they are ignored during the search.
Example: When I submit the string “ǨĴëĶś” as the FamilyName in the test environment, the system returns a match for “KJEKS.” This behaviour demonstrates that the search logic removes diacritics and normalises characters before performing the lookup.