# LookupPerson 🇫🇮, 🇩🇰
> [!NOTE]
> This version is no longer recommended for use and will be retired in the end of 2026.
## Overview
LookupPerson is a legacy person lookup service that retrieves person and address data from national population register sources using a personal number.
Use this service when you need to:
- retrieve person details from a supported country register
- validate whether a person record can be found
- receive structured identity and address data for onboarding or verification flows
### Key capabilities
- **Person lookup** — Search for a person using a national personal number
- **Structured response** — Receive normalized identity and address fields
- **Country-specific data** — Some response fields are specific to a supported country
## Availability
This legacy service should only be used for:
- **Denmark (`DK`)**
- **Finland (`FI`)**
> [!IMPORTANT]
> Sweden has a newer version and should not use this legacy LookupPerson endpoint.
## Ways of integrating LookupPerson
- **API** — Recommended integration method for this service
## Usage
### Typical flow
1. Send a `POST` request with `CountryCode` and `PersonalNumber`
2. Authenticate using your API key in the `Authorization` header
3. Inspect `WasFound`
4. If found, parse the `Person` object
### Input requirements
The service accepts the following core input:
- `CountryCode` — Supported country code, such as `FI` or `DK`
- `PersonalNumber` — National personal number for the person to look up
### Output
A successful response returns:
- `id` — request identifier
- `errors` — array of errors
- `WasFound` — indicates whether a person was found
- `Person` — person details when a match is found
## Core Functionalities
### Environments
**Test**
`https://test.zignsec.com`
**Production**
`https://api.zignsec.com`
### Authentication
Each request must be authenticated using your API key in the `Authorization` header.
### REST API
#### Headers
- `Authorization` — Your API key
- `Content-Type: application/json`
## API Endpoints
### Lookup person
`POST /v2/ekyc/lookupperson`
#### Request body
```json
{
"CountryCode": "FI",
"PersonalNumber": "291068-0520"
}
```
#### Example request
``` http
POST /v2/ekyc/lookupperson HTTP/1.1
Host: test.zignsec.com
Authorization: Your-API-Key
Content-Type: application/json
{
"CountryCode": "FI",
"PersonalNumber": "291068-0520"
}
```
#### Example response
```json
{
"id": "b56cc8df-a78e-4d27-b334-ba9c88a6d73d",
"errors": [],
"WasFound": true,
"Person": {
"PersonStatus": "Active",
"Gender": "Female",
"MainFirstName": null,
"FirstName": "Taneli",
"LastName": "Tammisto",
"DateOfBirth": "1968-10-29",
"BirthYear": 1968,
"BirthMonth": 10,
"BirthDayOfMonth": 29,
"Age": 57,
"PersonalNumber": "291068-0520",
"Address": "Ansatie 6 a 1",
"Address2": null,
"PostalCode": "01740",
"Location": null,
"City": "Vantaa",
"Municipality": "Vantaa",
"Province": null,
"CountryCode": "fi",
"Phone": null,
"Email": null,
"PhoneNumbers": null,
"_DataSource": "DP14",
"Url": null,
"FullName": "Taneli Tammisto",
"FiDomicileCode": "092",
"FiDomicile": "Vantaa",
"FiPopulationRegisterStatus": "000",
"FiPopulationRegisterStatusText": "The person is found",
"FiDateOfDeath": null
}
}
```
## Test data
Use the following test data in the test environment only.
[Finnish Test persons can be found here.](https://43660018.fs1.hubspotusercontent-na1.net/hubfs/43660018/Zignsec%20Support/FinishTestPersons%20(1).xlsx)
[Danish Test persons can be found here](https://43660018.fs1.hubspotusercontent-na1.net/hubfs/43660018/Zignsec%20Support/DanishTestPersons.xlsx)
## Response Model
### Top-level fields
- `id` — request identifier
- `errors` — returned errors, if any
- `WasFound` — `true` when a person record is found
- `Person` — person payload returned when a match exists
### Person fields
#### Common fields include:
- `PersonStatus`
- `Gender`
- `MainFirstName`
- `FirstName`
- `LastName`
- `DateOfBirth`
- `BirthYear`
- `BirthMonth`
- `BirthDayOfMonth`
- `Age`
- `PersonalNumber`
- `Address`
- `Address2`
- `PostalCode`
- `Location`
- `City`
- `Municipality`
- `Province`
- `CountryCode`
- `Phone`
- `Email`
- `PhoneNumbers`
- `_DataSource`
- `Url`
- `FullName`
#### Country-specific fields may also be present, such as:
- `FiDomicileCode`
- `FiDomicile`
- `FiPopulationRegisterStatus`
- `FiPopulationRegisterStatusText`
- `FiDateOfDeath`
#### PersonStatus:
- `Missing`Â or ""
- `Active`Â represents an active person and is the normal value.
- `Protected` – a person with protected identity
- `Emigrated` – a emigrated person will show this status for a "limited period".
- `Deceased` – a deceased person will show this status for a "limited period".
- `DeRegistered` – internal deletion code
- `Unknown status` – the earlier status was most likely Deceased or Emigrated but the indication is automatically lost after the above “limited period” has elapsed, and Unknown status is shown instead.
In case of a set PersonStatus the name and address fields are blanked out.
## Result Handling
- Success is typically indicated by an empty `errors` array and `WasFound: true`
- No result is indicated by `WasFound: false`
- Any processing issues are returned in `errors`
## Notes
- This is a legacy endpoint
- Only Denmark and Finland should use this version
- Sweden should use the newer version instead
- Response field availability can vary by country