1. Introduction

This document describes the CPR Direkte service interface for the service "ADRM - Match".

1.1. Purpose

The purpose of the service is to provide person data to CPR’s customers based on name and address searches. The service delivers data in the same record format as the batch product U08080P "Adressematch Person Ændringsudtræk", so batch customers can use the service to supplement or refresh data in their own systems between CPR batch runs.

2. Access

The following sections describe the access requirements for users of the service.

2.1. Customer Focus

Use of this service is aimed at private customers.

2.2. Access Control

Users must be authenticated by the CPR security system to use the service. In addition, users must be assigned a CPR Direkte security profile that grants access to the service.

3. Parameters

The service supports the following parameters:

Parameter: Addressing name format
You can choose whether addressing names are printed in either First name(s) Last name or Last name,First name(s) format.
Default value: Last name,First name(s)

Parameter: Exclude name and address protection
Indicates whether name and address data on persons with active name and address protection registered in CPR should be omitted.
Parameter values: Yes or No
Default value: Yes

Parameter: CPR-nr. subscription customer number
Indicates the customer number where the customer’s CPR-nr. subscriptions are registered.
Default value: (none)

Parameter: Last known address of deceased persons
You can choose whether the service delivers the last known address of deceased (CPR status code 90) persons in records containing address data.
Parameter values: Yes or No
Default value: No

If you wish to change the task’s parameters, you must contact CPR Customer Center.

4. Communication Protocol

Communication with the service takes place over a standard socket connection. Messages between the client application and the service are sent in fixed-length record format according to record descriptions in this document.

To perform match lookups, users must first be authenticated by the CPR security system, after which it is possible to send the search criteria. The following steps are performed on the same socket connection:

1. Connect to CPR Direkte
2. Send Login request
3. Read authentication token from Login response (or handle any errors indicated in the response)
4. Send Match request
5. Read data from Match response (or handle any errors indicated in the response)

Note that the CPR Direkte service will close the connection in the following cases:

• The login request fails, e.g., due to incorrect username/password
• More than 5 seconds pass between sending the Login response and the Match request
• After the client has received the Match response

5. Input data

This section describes the record types used to authenticate the user and perform match lookups.

5.1. Login request

Record sent to retrieve a token value from the CPR security system. Authentication is required to obtain a token value, which is necessary to perform lookups in CPR.

Record length: 35

Example:

ADRM,111190USER    Password

5.2. Login response

Record returned to the user in connection with a login request.

If ERROR NO is 00, the user can retrieve a token value from the TOKEN record field.

Record length: 28

Example (token value is KETDqhzM):

111190KETDqhzMUSER    000028

5.3. Match request

Record containing the search criteria related to the person to be looked up.

Matching rules are described below in the section Match rules.

Record length: 204

If a CPR-nr. (PNR) is known, this can be used to look up the person instead of name and address search criteria. The CPR-nr. is specified in the KUNDEREFNR record field. Please see the example below.

Match lookup examples:

Name and address:

111106KETDqhzMBRUGER  00ref-123456789   Per Andersen                                                      01011970

CPR-nr. (PNR is 1212123333):

111106KETDqhzMBRUGER  00PNR=1212123333

All search criteria:

111106KETDqhzMBRUGER  00ref-123456789  MPer Andersen                                                      010119703450                Allerød             Allerødvej                              1   02th

Note that only one of the POSTDISTRIKT or KOMMUNE fields should be filled in for address searches. The example shows both fields filled in.

5.4. Match response

Record containing the response for a match lookup.

If a person was found for the specified search criteria in CPR, data related to the person is returned in the DATA record field. Which records are returned in the DATA field is controlled by the customer’s task settings.

Record length: 28 + DATA LENGTH (total length provided in LENGTH record field)

5.5. Match rules

The following rules apply to Match request lookups:

• KUNDEREFNR must be specified if subscription set or delete is desired, as KUNDEREFNR is the key to the connection between the CPR register and the customer’s administrative system
• A specific KUNDEREFNR can only be used for one person
• The same person can, however, be subscribed with several different customer reference numbers
• NAVN for the person must always be specified. The detailed rules are:
  • there must be at least 2 full name parts
  • the name parts must be written in the correct order (first names middle names last names)
• In addition, FOEDDTO (date of birth) and/or address must be specified for identification of the person. If an address is provided then it must be correct. This means that persons can be looked up with the following combinations of search criteria:
  • Name and date of birth
    • Note that the date of birth must be correct when address is omitted
  • Name and address
  • Name, date of birth, and address
    • When name and address are specified, the date of birth is only used when there are several people having the same name at the same address. It is therefore possible to match a person even if the date of birth is incorrect, provided that the person’s name and address result in a unique match. If date of birth is provided then it must be formatted correctly (DDMMYYYY)
    • KOEN (gender) does not need to be specified, but if specified, one of the legal values must be used (K for female, M for male)
• When the address is used, the following detailed rules apply to the address fields:
  • Either POSTDISTRIKT or KOMMUNE must be specified, but not both
  • For both the POSTDISTRIKT and KOMMUNE fields, they can be filled in with either plain text e.g. "Allerød" or with code (postal code or municipality code e.g. 3450 and 201)
    • To increase the likelihood of a unique match, it is recommended to use postal code and municipality code instead of plain text
  • Likewise, the VEJ field can be filled in with CPR’s street code e.g. "199" or with plain text e.g. "Allerødvej"
    • To increase the likelihood of a unique match, it is recommended to use street code instead of plain text
  • HUSNR must be filled in
    • Not all Greenlandic addresses have a house number. In such cases, the HUSNR field must be filled in with the address’s building number (BNR)
  • ETAGE does not need to be correct if provided. The provided value is only used when there are several people having the same name at the same address. It is therefore possible to match a person even if the ETAGE value is incorrect, provided that the person’s name and other address search criteria result in a unique match.
  • SIDEDOER does not need to be correct if provided. The provided value is only used when there are several people having the same name at the same address. It is therefore possible to match a person even if the SIDEDOER value is incorrect, provided that the person’s name and other address search criteria result in a unique match.

Note the following exceptions to the above rules:

• If KUNDEREFNR starts with PNR=, the following 10 positions are interpreted as a PNR and all other identification fields are ignored (name, date of birth, gender, address)
• If KUNDEREFNR is filled in, does not start with PNR=, and all other identification fields are blank (gender, date of birth, name, address), the request is considered a requisition to extract data for the person who has the specified KUNDEREFNR
• If a transaction has ABON_TYPE 4 (deletion of address match subscription), only KUNDEREFNR is used for identification of the person/subscription. Any data in the other identification fields is ignored
• Persons with CPR status 50 (deleted CPR-nr.) or 60 (changed CPR-nr.) will never result in a match and will therefore never be subscribed. The valid CPR-nr. has taken over the changed/deleted CPR-nr. subscriptions

6. Output data

The service returns data in the form of fixed-length records. Which records are delivered in the response from the service depends on the customer’s task configuration. The following sections describe the data format for the records that can be delivered in the response.

The following descriptions of record structures are provided in Danish.

6.1. Recordtyper (DATA)

Oversigten viser, hvilke records der kan forekomme i DATA recordfeltet.

6.1.1. 000 Startrecord

Start record.

Format:

Recordlængde: 48

6.1.2. 001 Aktuelle data

Aktuelle data record.

Format:

Recordlængde: 404

Feltet ADRNVN kan leveres i formatet Fornavn(e) Efternavn eller Efternavn,Fornavn(e).

På inaktive personer (status 70, 80, eller 90) og personer med vejkode 9900 (status 3 eller 7) leveres ingen aktuel indenlandsk adresse.

Hvis personer har navne- og adressebeskyttelse leveres der ingen data i recordfelter markeret "beskyttet" medmindre det er aftalt med CPR-kontoret.

MATCHTYP overføres uændret fra input-filen.

6.1.3. 001B Aktuelle data med adresse UUID

Aktuelle data record med adresse UUID.

Format:

Recordlængde: 445

Feltet ADRNVN kan leveres i formatet Fornavn(e) Efternavn eller Efternavn,Fornavn(e).

På inaktive personer (status 70, 80, eller 90) og personer med vejkode 9900 (status 3 eller 7) leveres ingen aktuel indenlandsk adresse.

Hvis personer har navne- og adressebeskyttelse leveres der ingen data i recordfelter markeret "beskyttet" medmindre det er aftalt med CPR-kontoret.

MATCHTYP overføres uændret fra input-filen.

6.1.4. 002 Udlandsadresser

Udrejse record.

For personer med status 80 - udrejste. På personer med navneadressebeskyttelse leveres ingen udenlandske adresse oplysninger.

Format:

Recordlængde: 209

Hvis personer har navne- og adressebeskyttelse leveres der ingen data i recordfelter markeret "beskyttet" medmindre det er aftalt med CPR-kontoret.

6.1.5. 003 Kontaktadresser

Kontaktadresse record.

For personer med status 20, 70, 80 eller 90.

Format:

Recordlængde: 209

6.1.6. 004 Civilstand

Civilstand record.

Format:

Recordlængde: 40

Leveres kun til brug vedrørende pension. Det forudsættes, at alle personer under det pågældende kundenummer er pensionskunder.

6.1.7. 005 Værge med text felter

Værge med text felter record.

Format:

Recordlængde: 243

6.1.8. 006 Ægtefælle oplysninger

Ægtefælle oplysninger record.

Format:

Recordlængde: 538

Kan kun vælges til brug vedrørende pension. Leveres kun for afdøde personer.

Hvis ægtefællen har navne- og adressebeskyttelse leveres der ingen data i recordfelter markeret "beskyttet" jvf. CPR-loven § 38, stk 3.

6.1.9. 011 Flere kunderefnr

Flere kundereferencer record.

Leveres kun, hvis MATCHTYP = T eller R, og den indsendte person allerede findes i abonnement med et eller flere forskellige kundereferencenr. Personens nye kundereferencenr. bliver vist i feltet KUNDEREFNR, og det/de allerede eksisterende kundereferencenr. bliver vist i feltet KUNDEREFNR-ANDET-1. Det vil sige, at der bliver leveret en record 011 for hvert kundereferencenr. der allerede er i abonnement på samme person.

Format:

Recordlængde: 102

6.1.10. 012 Personnummer abonnement

Personnummer abonnement på andet kundenummer record.

Leveres kun, hvis MATCHTYP = E, T eller R. Offentlige kunder kan få udtrukket personnummer på alle udtrukne personer.

Format:

Recordlængde: 37

6.1.11. 013 PNR Oplysninger

Personnummeroplysninger record.

Hvis personen er udtrukket som følge af personnummer.

Format:

Recordlængde: 56

6.1.12. 050 Kreditadvarsel

Kreditadvarsel record

Format:

Recordlængde: 43

6.1.13. 052 Værge med text felter og værgemålstype

Værge med text felter record.

Format:

Recordlængde: 258

6.1.14. 999 Slutrecord

Slut record i et andet format.

Format:

Recordlængde: 34

7. Help

The following resources can be used if errors or problems are experienced when calling the service:

• CPR Documentation Site
• CPR Direkte code examples
• CPR Operational Status
• CPR Service Desk

8. Appendix - Subscriptions, password requirements, and error codes

8.1. Subscription types

The service supports the creation and deletion of both address match and CPR-nr. subscriptions in connection with match lookups. Subscriptions make it possible for CPR batch customers to receive ongoing updates on the persons for whom subscriptions exist. Read more about subscriptions on the CPR website.

The following subscription type values may be specified in the ABON_TYPE record field in Match request.

• 0: No subscription action
• 1: Create CPR-nr. subscription
• 2: Create address match subscription
• 3: Delete CPR-nr. subscription
• 4: Delete address match subscription

Note that subscription types 1 and 3 may only be used in connection with PNR (CPR-nr.) subscriptions, i.e., in cases where KUNDEREFNR in Match request is a PNR (begins with PNR=). Likewise, subscription types 2 and 4 may only be used in connection with match lookups (KUNDEREFNR in Match request is not a PNR).

8.2. Password requirements

The password must be 8 characters.

• At least 1 lowercase letter (a-z)
• At least 1 uppercase letter (A-Z)
• At least 1 digit (0-9)
• At least one special character: ~ ` ! @ # $ % ^ * ( ) _ - + = , . / \ { } [ ] ; :
• There is a check for uppercase and lowercase letters
• The characters < > & ? ' æ ø and å cannot be used
• The password can only be changed once per day
• It is not allowed to change to a password that has been used previously

8.3. Error numbers and error texts

This section describes the possible error numbers that may occur in the FEJLNR field in the response from the service, e.g., 00 ("No error").

Errors from the CPR security system during authentication:

• 01: USER-ID/PASSWORD not correct
• 02: PASSWORD expired, NEW PASSWORD required
• 03: NEW PASSWORD does not meet requirements
• 16: IP address incorrect

Errors from the service due to incorrect data in the request:

• 04: No access to CPR (CTSERVICE is temporarily closed)
• 05: PNR unknown in CPR
• 06: Unknown KUNDENR
• 07: Timeout / new LOGON required
• 08: No access to CPR (CTSERVICE is not active)
• 10: ABON_TYPE unknown
• 11: DATA_TYPE unknown
• 12: KUNDEREFNR. MUST BE FILLED IN
• 13: KUNDEREFNR. IS IN USE FOR ANOTHER PERSON
• 14: USER-ID does not have access to the transaction (CTPROFIL is temporarily closed)
  • or Setting subscription is not allowed
• 15: Not found in CTADRAB table
• 17: "PNR=" is not specified
• 18: USER-ID does not have access to the transaction (CTPROFIL is not active)
• 19: "PNR=" must not be specified for subscription type 2 and 4
• 24: USER-ID does not have access to the transaction (CTPERSKOD_PROFIL is temporarily closed)
• 28: USER-ID does not have access to the transaction (CTPERSKOD_PROFIL is not active)
• 29: KUNDEREFNR starts with a date, which is not allowed for subscription type 2 and 4
• 115: Floor contains incorrect letters, characters, or numbers
• 126: House number/letter contains incorrect letters, characters, numbers
• 143: Side-door number contains incorrect letters, characters, or numbers
• 7015: Postal code/district does not exist in CPR
• 7016: Postal district exists multiple times. Enter postal code
• 7056: The street does not exist in CPR
• 7100: There must be blanks after the entered street code
• 7102: Enter gender. M for male or K for female
• 7144: Enter a name
• 7168: Date must be correct and less than or equal to today’s date
• 7251: Either CPR-nr., date of birth, or address must be filled in
• 7252: Either CPR-nr., date of birth, or address must be filled in
• 7255: No persons met the search criteria. Narrow down differently
• 7256: The search returns more than one person. Narrow down differently.
• 7257: Municipality or postal district must be filled in
• 7259: House number must be filled in when street is filled in
• 7578: Municipality does not exist in CPR
• 7579: Municipality is not a valid municipality
• 7677: Fill in either municipality or postal district
• 7713: There must be at least two unabbreviated names
• 8971: KUNDEREFNR starts with a date. This is not allowed

Errors from the service where it is recommended to contact CPR if the error occurs repeatedly:

• 40: Task does not exist
• 41: Task configuration missing
• 42: Task batch relation missing or inactive
• 43: Task version missing or inactive
• 44: No tasks found for the specified transaction code
• 99: Server error. See log