How to connect DQE suggestion and validation endpoints for optimal address quality with minimal unnecessary API calls.
Integration patterns
DQE recommends a two-level approach:
- Level 1 - Address suggestion - choose single line or type down depending on your form design
- Level 2 - RNVP validation safety net - trigger only when the user entered free text or modified a DQE suggestion
Integration flow
Label field - display only
The Label field is formatted for the suggestion dropdown only. Its format varies by country and may include separators, parentheses, or bracket-wrapped numbers. Do not use it to populate address fields - always use the structured fields returned alongside it.
Street numbers in brackets (e.g. [30] RUE DE LA PAIX) indicate that the number is not found in the DQE reference database. DQE still returns the rest of the address correctly formatted so users can proceed. Consider displaying bracketed numbers in a muted style to signal that the number may need verification - it could appear in a future database update.
Street selected without a number
When a user selects a street without entering a street number, the API returns the street match but signals that numbers exist for that street. Detect this case and present the available numbers from the response already received - no additional API call is needed. This applies to all autocomplete modes: Standard API SINGLEV2 and ADR, RESTful SINGLE and FunnelAddress.
Detection condition
| Field | Value | Meaning |
|---|---|---|
| valid_num | "0" |
No valid number matched |
| ListeNumero | non-empty | Known numbers exist on this street |
Complement field
Map your complement form field to Complement (Classic: SINGLEV2 / ADR) or AdditionalAddress (RESTful: single / funneladdress).
After the user selects an address, call the dedicated complement step - COMPLV2 / COMPL (Classic) or compl / funnelcompl (RESTful) - and present the returned options to the user.
Language of returned results
For most countries, address data exists in a single language and the language of the returned results depends entirely on the reference database - you cannot change it.
For some countries, the database contains entries in multiple languages or scripts. In that case, the Langue parameter acts as a strict language filter: only results tagged with the requested language are returned. Without it, all language versions may be returned simultaneously.
Countries where Langue filters by language
| Country | Supported values | Effect |
|---|---|---|
| Japan (JPN) |
JP · JK · EN
|
JP = kanji · JK = katakana · EN = romaji. Without Langue, all three scripts are returned. |
| Hong Kong (HKG) |
EN · ZH
|
EN = English · ZH = Chinese. Setting Langue=EN on Chinese input (or vice versa) returns zero results. |
| Thailand (THA) |
EN · TH
|
EN = Latin transliteration · TH = Thai script. Without Langue, both language versions are returned simultaneously (e.g. searching by postal code returns Thai and English results mixed). |
Langue value does not match any entry in the database for a given input, the API returns zero results. Ensure the language you request is consistent with the script of the address being entered.Address correction (RNVP)
When a RNVP call is triggered, display the correction to the user as a popup, always preserving the option to keep their original input. Add Modification=O to the request to receive a field-by-field breakdown.
| Key | Description | Values |
|---|---|---|
| Status_Modification RESTful: IsAddressChanged |
Indicates whether DQE modified the address. |
O / N (Classic) · 1 / 0 (RESTful) |
| Code_Modification RESTful: ChangedAddressTag |
5-character binary string - one position per field (additional address · address · dependent locality · zip code · city). See CheckAddress reference. Example: 00011
|
5-char binary |
| DQECodeDetail RESTful: DQEDetailCode |
Validation result code of the address returned by DQE - not the original user input. Example: input 12 RUE PAIX PARIS → DQE returns 12 RUE DE LA PAIX 75002 PARIS with DQECodeDetail=10 (valid). Full list with recommended UI messages in the CheckAddress reference. |
Numeric code |
Recommended user messages by validation code
The validation code (DQECodeDetail in Classic API, DQEDetailCode in RESTful) indicates the quality of the address returned by the API. The table below maps each code to an internal description (for support and integration teams) and a recommended end-user message.
| Code | Description | Internal Description | UI Display |
|---|---|---|---|
| 10 | Correct address | Valid address | Valid address |
| 20 | Correct address (street not recognized, but it is a CEDEX or P.O. box) | Valid address | Valid address |
| 21 | Small town, street number out of range | Please confirm the address with the client (street number does not exist) | Please check your postal address |
| 22 | Small town, street number missing (the rest of the address is correct) | Please confirm the address with the client (street number missing) | Please check your postal address |
| 23 | Large city, street number out of range | Please confirm the address with the client (street number does not exist) | Please check your postal address |
| 24 | Large city, street number missing (the rest of the address is correct) | Please confirm the address with the client (street number missing) | Please check your postal address |
| 25 | CEDEX address unknown to CEDEXA (if CEDEXA is active) | Valid address | Valid address |
| 30 | Small town, street not recognized | Please confirm the address with the client (street name not found) | Please check your postal address |
| 31 | Small town - street not recognised or missing; district info recognised but insufficient to determine the street. France only. | Please confirm the address with the client (street name not found) | Please check your postal address |
| 40 | Not expected in current cloud deployments. Defined for compatibility. | - | - |
| 41 | Small town, street missing | Please confirm the address with the client (street name missing) | Please check your postal address |
| 50 | Large city, street not recognized | Please confirm the address with the client (street name not found) | Please check your postal address |
| 51 | Large city, street not recognised or missing (district information recognised but insufficient to determine the street). France only. | Please confirm the address with the client (street name not found) | Please check your postal address |
| 60 | Not expected in current cloud deployments. Defined for compatibility. | - | - |
| 61 | Large city, street missing | Please confirm the address with the client (street name missing) | Please check your postal address |
| 70 | Postal code / city mismatch - street present | Address is incorrect. The postal code/city do not match. | Please check your postal address |
| 71 | Not expected in current cloud deployments. Defined for compatibility. | - | - |
| 80 | Postal code / city mismatch - street missing | Address is incorrect. The postal code/city do not match. | Please check your postal address |
| 81 | Input address block empty. Not returned for France. | Address not filled in | Please check your postal address |
| 90 | International address detected - the input country code does not seem to match the input address. | Address appears international - country code does not match | Please check your postal address |
| 95 | Missing or incorrect country code | Check and correct the country code in input | Please check your postal address |
Related to