### Version 5 (Latest)
### Overview
This service enables the lookup of a Swedish person’s identity data using their Personal Identification Number (Personnummer) and optionally the postal code (zip code). It returns identity details including full name, address, phone numbers, and other relevant information based on Swedish government data sources.
### Supported Country
- **Sweden**
### Data Source
- Official Swedish Population Registry
## Core Functionalities
### Environments
We provide the following environments for your use:
- **Test (TEST) Environment:** `https://test-gateway.zignsec.com/core/api/`
- **Production (PROD) Environment:** `https://gateway.zignsec.com/core/api/`
### Authentication
Each request to our API should be authenticated by sending your subscription key in the “Authorization” header. Our support creates subscription keys for you (a pair for each environment), and it’s highly recommended to regularly rotate the keys (currently it’s done by sending a support request, but please let us know if you’d like to automate it).
If you need different configurations it’s possible to register multiple tenants and configure them differently.
### REST API
#### Headers
| Header | Description | Required |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Authorization | This header parameter is the subscription key you received from ZignSec during the registration process. Example: Authorization: 123456add0cff22873c428e987654321 | Yes |
| Content-Type | Specifies the media type of the request body data. Set to application/json if JSON object. | Yes |
#### OpenAPI documentation
##### Live documentation
- [Swagger UI (zignsec.com)](https://test-gateway.zignsec.com/#/Register%20Checks/postLookupPersonSe)
#### API Endpoint
**POST /sessions/lookup_person/se**
**Description**: This endpoint retrieves detailed identity information from the Swedish Population Registry using a valid Swedish Personal Identification Number (Personnummer), and optionally, a zip code for additional specificity.
#### **Request Body:**
The request can include the following parameters in JSON format:
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `personalNumber` | String | Yes | The Swedish Personal Identification Number (Personnummer) of the person, formatted as `YYYYMMDDXXXX`. |
| `zip_code` | String | No | Optional Swedish postal code (zip code). Example: `19534`. |
#### **Example Request:**
``` bash
curl -X 'POST' \
'https://test-gateway.zignsec.com/core/api/sessions/lookup_person/se' \
-H 'accept: application/json' \
-H 'authorization: Your_Api_Key' \
-H 'Content-Type: application/json' \
-H 'x-csrf-token: VxUQXABddCtjZldSHAMvSl0HT2lLFAQCftX2gd8IN7za1WK2-qv18Xav' \
-d '{
"gdpr_user_id": "string",
"metadata": {
"ssn": "195012112222"
},
"relay_state": "string",
"webhook": "string"
}'
```
### Response Details
A successful response returns the requested identity information of the person associated with the given Personal Identification Number and, if provided, the postal code.
| **Parameter** | **Type** | **Description** |
| ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Unique identifier for the data. |
| `age` | `integer` | Age of the individual. |
| `birthDate` | `string` (date) | Full birth date of the individual in `YYYY-MM-DD` format. |
| `birthDayOfMonth` | `string` | Day of the month when the individual was born. |
| `birthMonth` | `string` | Month of birth in numeric format. |
| `birthYear` | `string` | Year of birth. |
| `gender` | `string` | Gender of the individual. |
| `apartmentNumber` | `string` (null) | Apartment number, if available; otherwise `null`. |
| `city` | `string` | City of residence. |
| `co` | `string` (null) | Care-of address, if available; otherwise `null`. |
| `entrance` | `string` (null) | Entrance details, if available; otherwise `null`. |
| `extendedAddress` | `string` (null) | Additional address details, if available; otherwise `null`. |
| `extraAddressField` | `string` (null) | Extra address information, if available; otherwise `null`. |
| `firstName` | `string` | Complete firstname of the individual |
| `foreignAddress1` | `string` (null) | First line of the foreign address, if applicable; otherwise `null`. |
| `foreignAddress2` | `string` (null) | Second line of the foreign address, if applicable; otherwise `null`. |
| `foreignAddress3` | `string` (null) | Third line of the foreign address, if applicable; otherwise `null`. |
| `foreignCountry` | `string` (null) | Foreign country, if applicable; otherwise `null`. |
| `givenName` | `string` | Given name of the individual. |
| `lastName` | `string` | Last name or family name of the individual. |
| `middleName` | `string` (null) | Middle name, if applicable; otherwise `null`. |
| `street` | `string` | Full street address. |
| `streetName` | `string` (null) | Name of the street, if available; otherwise `null`. |
| `streetNumber` | `string` (null) | Street number, if available; otherwise `null`. |
| `surName` | `string` | Complete surname or family name of the individual. |
| `zipCode` | `string` | Postal code for the address. |
| `phoneNumbers` | `array[string]` | List of phone numbers associated with the individual. |
| `phoneTypes` | `array[string]` | Corresponding types of phone numbers (e.g., Mobile, Other). |
| `ssn` | `string` | Social Security Number (SSN) of the individual. |
| `ssnStatus` | `string` | Status of the SSN Possible values: `Active, Deceased, Protected, DeRegistered, Emigrated` |
| `responseCode` | `string` | Response code indicating the success or failure of the operation. Possible values: `Ok, Deceased, FraudFlag, DeRegistered, NotFound, Blocked` |
| `responseMessage` | `string` | Additional information or message from the response, if any (empty if no message). |
#### **Example Full Response:**
```json
{
"data": {
"id": "ab534e23-a574-4bd8-97ef-dd572c4b99e0",
"result": {
"additional": {
"age": 74,
"birthDate": "1950-12-11",
"birthDayOfMonth": "11",
"birthMonth": "12",
"birthYear": "1950",
"gender": "female"
},
"basic": {
"apartmentNumber": null,
"city": "ANGERED",
"co": null,
"entrance": null,
"extendedAddress": null,
"extraAddressField": null,
"firstName": "Anna Maria",
"foreignAddress1": null,
"foreignAddress2": null,
"foreignAddress3": null,
"foreignCountry": null,
"givenName": "Anna",
"lastName": "Martinsson",
"middleName": null,
"street": "Vintergatan 2 D",
"streetName": null,
"streetNumber": null,
"surName": "Martinsson",
"zipCode": "42431"
},
"phoneNumbers": {
"phoneNumbers": [
"070-5012130",
"070-5012133",
"070-5012136",
"070-5012139",
"070-5012142",
"070-5012145"
],
"phoneTypes": [
"Mobile",
"Other",
"Mobile",
"Mobile",
"Other",
"Mobile"
]
},
"responseCode": "Ok",
"responseMessage": "",
"ssn": {
"ssn": "195012112222"
},
"ssnStatus": "Active"
}
}
}
```
### Error Handling
Errors may occur due to issues with authentication, invalid request format, or the person not being found in the registry.
For details please view openAPI specification found here: [Swagger UI (zignsec.com)](https://test-gateway.zignsec.com/#/Register%20Checks/postLookupPersonSe)
### How to test
Here is a link to an excel sheet which contains test data which can be used to test the products.
[Link to testdata](https://25357801.fs1.hubspotusercontent-eu1.net/hubfs/25357801/Support%20Files/TestdatabasPersoner.xlsx)