API Specification

The purpose of the Identity Validation API is to provide an easy solution to implement electronic identity validation/verification. In this section you can read about how to create the request to the web service and what response you will get back.

Identity Validation Request

The identity validation API takes some input and returns an identity validation response containing validation codes for that input.

You can perform a call to the identity validation API by making a GET request of the form:

https://apps.conzoom.eu/api/v1/eidv/validate?in_adr={adr}&in_name={name}&in_dob={dob}&in_person_id={pid}

Query String Parameters

You are able to provide the following query parameters:

in_adr - The residential address of the person - provided as a single line.
in_name - The name of the person. First name before last name. At least two name parts are required for a successful match, and those two name part must be spelled out (i.e. not just initials).
in_dob - Date-of-birth of the person - provided as YYYY-MM-DD.
in_person_id - The national identity number of the person. Currently, only Danish CPR numbers are supported - either as DDMMYY-XXXX or DDMMYYXXXX.
in_strict_name_match - (Optional) If true, a name_match: match is returned only if all name parts match one-to-one with the CPR registry, otherwise a fuzzy_match. If false, name_match: match is returned even if only a subset, which must include the last name, of the name parts is provided. Default: false.
in_extended_address_match - (Optional) If true, adr_match_level added to the result to indicate at which level the address was matched if a adr=fuzzy_match. Default: false.
in_phone_1 - (Optional) Phone number one to validate for the person, only used in case the person is found. Currently, the only supported format is an 8-digit Danish phone number.
in_phone_2 - (Optional) Phone number two to validate for the person, only used in case the person is found. Currently, the only supported format is an 8-digit Danish phone number.

To be able to validate a person you need as a minimum to provide one of the following combinations of input:

in_name and in_adr
in_name and in_dob
in_name and in_person_id

Identity Validation Response JSON

For each request, the identity validation service returns a JSON object containing the validation codes for the input. The codes will never be null, and will always have a value.

The response of a validation request will look like this:

    {
        "person_found": {boolean},
        "name_adr_protected": {boolean},
        "person_status": {person_status_code}
        "adr": {address_validation_code},
        "adr_match_level": {address_match_level},
        "name": {name_validation_code},
        "dob": {dob_validation_code},
        "person_id": {person_id_validation_code}
        "phone_1": {phone_validation_code}
        "phone_2": {phone_validation_code}
    }

The person_found property will contain a boolean value to indicate whether we could find the person or not. The possible values and their meaning are listed below:

true - We were able to find a person using the provided input. You can use the other match codes to assess the quality of the match.
false - We were not able to find a person, and all other match codes can be ignored. In this case, all validation codes will have the value not_found.

The name_adr_protected property will contain a boolean value to indicate whether the person is name and address protected. For protected persons it's not possible to obtain their current name and address. The possible values and their meaning are listed below:

true - The person is name and address protected, and we are not able to verify if the provided name and address are still valid or if they have changed.
false - The person's name and address could be obtained, and we were able to verify if the provided nane and address are valid and current.

The person_status property will contain the status of the matched person - as provided by the underlying registry.

unk - The status of the person is unknown - either because the person could not be found or because the underlying registry does not contain status information.
norm - The status of the person is normal, i.e. the person is alive and has no special status.
dead - The person is deceased.
expat - The person is expatriated, i.e. not living in the country of the registry anymore.
miss - The person is missing, i.e. there's no information in the registry about the whereabouts of the person.

The adr property will contain a validation code for the input address provided in the request. The possible values and their meaning are listed below:

match - We were able to find the person using the address or were able to verify the address by looking up the person using other information.
fuzzy_match - We were able to find a person on a similar address. This may be due to spelling mistakes or minor deviations in the address, e.g. missing suite identifier.
no_match - We were able to find a person, but the current address does not match the address in the request.
not_provided - No address was provided in the request.
not_found - No matching person could be found.

For in_extended_address_match=true we return the adr_match_level code indicating at which level a fuzzy_match (or match) from property adr has been matched. For adr=match this will always be suite. For fuzzy_match it will be one of the following.

suite - Match was made to suite level. This is a exact match.(adr=match)
house_number - We were able to match the input address to housenumber but either suite is missing or wrong.
street - We were able the match the input address to the street but either the housenumber and/or letter is missing or wrong.
postcode - We were able to match the input address only to the correct postcode. Street was missing or wrong.
no_match - We could not match any part of the input address or no address provided(adr=no_match/not_provided)

The name property will contain a validation code for the input name provided in the request. The possible values and their meaning are listed below:

match - We were able to find a person using the name or were able to verify the name by looking up the person using the person id.
fuzzy_match - We were able to find a person using a similar name. This could be due to spelling mistakes. If in_strict_name_match is true a fuzzy match is also returned, if some of the provided name parts are missing.
no_match - We were able to find a person, but the current name does not match the name in the request.
not_provided - No name was provided in the request.
not_found - No matching person could be found.

The dob property will contain a validation code for the date-of-birth provided in the request. The possible values and their meaning are listed below:

match - We were able to find a person using the date-of-birth, or we were able to find the person using the provided person id, and the date-of-birth matches the information contained in the person id.
no_match - We were able to find a person, but the actual date-of-birth does not match the date-of-birth in the request.
not_provided - No date-of-birth was provided in the request.
not_found - No matching person could be found.

The person_id property will contain a validation code for the person identity number in the request. The possible values and their meaning are listed below:

match - We were able to find a person using the provided person id, and the provided name matches the current name.
no_match - We were able to find a person, but the person id does not match the person id in the request.
not_provided - No person id was provided in the request.
not_found - No matching person could be found.

The phone_1 and phone_2 properties will contain a validation code for the phone numbers provided. The possible values and their meaning are listed below:

landline - The phone number matches a landline number of the person found.
mobile - The phone number matches a mobile number of the person found.
no_match - We were able to find a person, but the phone number provided did not match any of the phone numbers belonging to that person.
not_provided - No input phone number was provided in the request.
not_found - No matching person, so we cannot validate the given phone number.