On-Demand Address Cleanse & Update
Also known as Cleanse and Standardize
| Product Code(s) | Not Applicable |
| Option(s) | None |
| Monitoring Available | No |
| Interface | REST |
| Method | GET |
| Format(s) | JSON |
| Service | Company |
| {version} | 6.0 |
| 6.0 Released On | March 10, 2017 |
The D&B Direct API provides address standardization in two features: On-Demand Single Entity Resolution and On-Demand Address Cleanse & Update. The purpose of these features is to produce machine sortable mailing addresses that are optimized for accurate and quick delivery.
The On-Demand Address Cleanse & Update feature only performs the address cleanup service. To locate a D-U-N-S Numbers while cleansing address records, refer to the On-Demand Single Entity Resolution feature.
Update History
- July 10, 2015 (All Versions): Requests for country codes BV, CU, GS, IM, KP, MN, BQ, CW, SX, NU, PW, TL, UM, and WF will return a CM007 response code instead of PD005.
- July 10, 2015 (v5.0 SOAP/REST): Requests for companies domiciled in Germany (country code DE) require that an OrderReasonCode value be included per local regulations. The response code CM003 will be returned if the parameter is missing or a CM001 if the value is not valid.
Feature Request
IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.
Overview
For cleansing, a primary address (building number and street name, post office box or rural route number) is required in combination with an organization name, city, state, country and postal code to meet one of the following conditions:
1. For locations within the United States: primary address plus either (a) state abbreviation and ZIP code, (b) city name and ZIP code, or (c) city name with state abbreviation.
2. For locations outside of the United States: country code, primary address plus either (a) state, province or prefecture name and postal code, (b) city name and postal code, or (c) city name with name of the state, province or prefecture.
Global Availability
The Company_CleanseAndStandardize data layer is available for businesses domiciled in the following countries:
| Country | ISO Code |
|---|---|
| United States of America | US |
| Belgium | BE |
| France | FR |
| Germany | DE |
| Italy | IT |
| Netherlands | NL |
| Portugal | PT |
| Spain | ES |
| United Kingdom | GB |
| Australia | AU |
| New Zealand | NZ |
| Andorra | AD |
| Anguilla | AI |
| Antigua & Barbuda | AG |
| Aruba | AW |
| Bahamas | BS |
| Barbados | BB |
| Belize | BZ |
| Bermuda | BM |
| Bolivia | BO |
| British Virgin Islands | VG |
| Canada | CA |
| Cayman Islands | KY |
| Chile | CL |
| Colombia | CO |
| Costa Rica | CR |
| Denmark | DK |
| Dominica | DM |
| Dominican Republic | DO |
| Ecuador | EC |
| El Salvador | SV |
| Faero Islands | FO |
| Finland | FI |
| Greenland | GL |
| Grenada | GD |
| Guatemala | GT |
| Guyana | GY |
| Haiti | HT |
| Honduras | HN |
| Ireland | IE |
| Jamaica | JM |
| Japan | JP |
| Luxembourg | LU |
| Mexico | MX |
| Monaco | MC |
| Montserrat | MS |
| Netherlands Antilles | AN |
| Bonaire, Sint Eustatius And Saba | BQ |
| Curaçao | CW |
| Sint Maarten (dutch) | SX |
| Nicaragua | NI |
| Norway | NO |
| Panama | PA |
| Saint Kitts & Nevis | KN |
| Saint Lucia | LC |
| Saint Vincent | VC |
| San Marino | SM |
| Suriname | SR |
| Sweden | SE |
| Taiwan | TW |
| Trinidad And Tobago | TT |
| Turks And Caicos | TC |
| Venezuela | VE |
| Afghanistan | AF |
| Albania | AL |
| Algeria | DZ |
| American Samoa | AS |
| Angola | AO |
| Argentina | AR |
| Armenia | AM |
| Austria | AT |
| Azerbaijan | AZ |
| Bahrain | BH |
| Bangladesh | BD |
| Benin, Peoples Republic of | BJ |
| Bhutan | BT |
| Bosnia And Herzegovina | BA |
| Botswana | BW |
| Brazil | BR |
| Brunei | BN |
| Bulgaria | BG |
| Burkina Faso | BF |
| Burma (myanmar) | MM |
| Burundi | BI |
| Belarus | BY |
| Kampuchea (prev. Cambodia) | KH |
| Cameroon | CM |
| Cape Verde, Republic of | CV |
| Central Africa Republic | CF |
| Chad, Republic of | TD |
| China, Peoples Republic of | CN |
| Christmas Island | CX |
| Comoros Republic | KM |
| Congo Democratic Republic | CD |
| Cook Islands | CK |
| Croatia | HR |
| Cyprus | CY |
| Turkish Republic of Northern Cyprus | XT |
| Czech Republic | CZ |
| Djibouti | DJ |
| Egypt | EG |
| Equatorial Guinea | GQ |
| Eritrea | ER |
| Estonia | EE |
| Ethiopia | ET |
| Falkland Islands | FK |
| Fiji | FJ |
| French Guiana | GF |
| French Polynesia/tahiti | PF |
| Gabon Republic | GA |
| Gambia | GM |
| Georgia | GE |
| Ghana | GH |
| Gibraltar | GI |
| Greece | GR |
| Guadeloupe | GP |
| Guam | GU |
| Guinea Bissau | GW |
| Guinea, Republic of | GN |
| Hong Kong SAR | HK |
| Hungary | HU |
| Iceland | IS |
| India | IN |
| Indonesia | ID |
| Iran | IR |
| Iraq | IQ |
| Israel | IL |
| Ivory Coast/cote D'ivoire | CI |
| Jordan | JO |
| Kazakhstan | KZ |
| Kenya | KE |
| Kiribati | KI |
| Korea, Republic of | KR |
| Kuwait | KW |
| Kyrgyzstan | KG |
| Laos | LA |
| Latvia | LV |
| Lebanon | LB |
| Lesotho | LS |
| Liberia | LR |
| Libya | LY |
| Liechtenstein | LI |
| Lithuania | LT |
| Macao SAR | MO |
| North Macedonia | MK |
| Madagasgar | MG |
| Malawi | MW |
| Malaysia | MY |
| Maldives | MV |
| Mali | ML |
| Malta | MT |
| Marianas Islands | MP |
| Marshall Islands | MH |
| Martinique | MQ |
| Mauritania | MR |
| Mauritius | MU |
| Moldova | MD |
| Montenegro | ME |
| Morocco | MA |
| Mozambique | MZ |
| Namibia | NA |
| Nauru | NR |
| Nepal | NP |
| New Caledonia | NC |
| Niger | NE |
| Nigeria | NG |
| Norfolk Island | NF |
| Oman | OM |
| Pakistan | PK |
| Papua New Guinea | PG |
| Paraguay | PY |
| Peru | PE |
| Philippines | PH |
| Poland | PL |
| Qatar | QA |
| Reunion Island | RE |
| Romania | RO |
| Russian Federation | RU |
| Rwanda | RW |
| Saint Helena | SH |
| Saint Pierre Et Miquelon | PM |
| Sao Tome & Principe | ST |
| Saudi Arabia | SA |
| Senegal | SN |
| Serbia | RS |
| Seychelles | SC |
| Sierra Leone | SL |
| Singapore | SG |
| Slovakia | SK |
| Slovenia | SI |
| Solomon Islands | SB |
| Somalia | SO |
| South Africa | ZA |
| Sri Lanka | LK |
| Sudan | SD |
| South Sudan | SS |
| Eswatini | SZ |
| Switzerland | CH |
| Syria | SY |
| Tajhikstan | TJ |
| Tanzania | TZ |
| Thailand | TH |
| Togo | TG |
| Tokelau Islands | TK |
| Tonga | TO |
| Tunisia | TN |
| Turkiye | TR |
| Turkmenistan | TM |
| Tuvalu | TV |
| Uganda | UG |
| Ukraine | UA |
| United Arab Emirates | AE |
| Uruguay | UY |
| Uzbekistan | UZ |
| Vanuatu | VU |
| Vietnam | VN |
| Western Samoa | WS |
| Yemen | YE |
| Zambia | ZM |
| Zimbabwe | ZW |
| Congo | CG |
| Puerto Rico | PR |
| Holy See (vatican City State) | VA |
| Serbia & Montenegro | CS |
| Kosovo | XK |
| Micronesia, Federated States of | FM |
Data Layer Entitlement
For customers in U.S. and Canadian markets, the API is provisioned for specific collections of products, reports, and/or features (collectively referred to as data layers) for production and trial usage. Entitlement is not required for testing in the sandbox environment.
- This feature is entitled as "On-Demand Address Cleanse & Update" for D&B Direct 2.0 customers.
For customers in the UK, Ireland, Belgium, Netherlands and Luxembourg markets, the API is provisioned as a specific set of data layers for production, trial, and sandbox usage.
- This particular data layer is NOT included in the D&B Direct Onboard suite.
Specification
GET https://direct.dnb.com/V6.0/organizations?TerritoryName=CA&CountryISOAlpha2Code=US&cleanseandstandardize=true&OrganizationName=Gorman%20Manufacturing Authorization: <My Token>
| Name | Characteristics |
|---|---|
| ApplicationTransactionID | string up to 64 chars., Optional Unique Transaction ID of the request generated by the service |
| TransactionTimestamp | dateTime, Optional The date and time when this request was created. When the request is from an intermediary, such as a workflow manager or service bus, this is the date and time when the message was sent to the D&B function, i.e., the date and time when the xml document was created by the requesting intermediary. |
| SubmittingOfficeID | string up to 64 chars., Optional A number that identifies the system or the software application from where this request originated. / A number used to uniquely identfy the D&B business segment or delivery channel from where this request originated. |
| OrganizationName | string up to 256 chars., Optional Text recording the name of the inquired organization by which it is known / identified. |
| StreetAddressLine-n (Can repeat twice) | string up to 240 chars., Optional |
| PrimaryTownName | string up to 64 chars., Optional The name of the town or city recognized by the Postal Authority for delivering mail. |
| CountryISOAlpha2Code | string at least 2 chars. up to 2 chars., Required The two-letter country/market code, defined in the ISO 3166-1 scheme published by International Organization for Standardization (ISO), identifying the country/market for this address. |
| CountyName | string up to 64 chars., Optional The name of the primary administrative division within the Territory or Country. Clarification Note: As a guiding principle this is a geographic area which would be classified as a Province (except Canada) or a County. In the U.S. this would be a county within a State. In the UK this would be a county in one of the Home Nations. In Republic Of Ireland, this would be a county and there would be no Territory. |
| TerritoryName | string up to 64 chars., Optional The name of the locally governed area which forms part of a centrally governed nation. Clarification Note: As a guiding principle this is a geographic area which could theoretically exist as a separate nation. In the U.S. this would be a State. In the UK this would be one of the Home Nations. |
| PostalCode | string up to 32 chars., Optional An identifier used by the local country Postal Authority to identify a particular geographic location. For example, in Belgium, Postal Code 9000 identifies the town of GHENT. |
| CustomerReferenceText-n | string at least 1 chars. up to 240 chars., Optional(up to 5x) A freeform reference string provided by the customer to be linked to the product in order to support subsequent order reconciliation. |
| CustomerBillingEndorsementText | string at least 1 chars. up to 240 chars., Optional Text that is filled in by customer and commonly contains requesting individual or department name, or customer's own account/reference number and/or name for the case on which the product was provided.This text is a reference used during the billing process. |
Endpoint
Use the following endpoint for requesting this feature. The {version} is dependent on the underlying service delivering the response.
NOTE: While "organizations" is part of this endpoint, there is no service by this name. Many D&B Direct calls have a similar structure; however, the {version} component is based on the SERVICE to which a given product is associated.
| REST (Company) |
|---|
| GET https://direct.dnb.com/V{version}/organizations?cleanseandstandardize |
Testing
This operation will return a static set of results in the D&B Direct test environment (sandbox), regardless of the request parameters.
Feature Response
NOTE: The D&B Direct REST implementation uses the BadgerFish approach for JSON with some minor variations.
Specification
The following is a list of the possible data fields returned by this operation in the JSON response. Samples are provided for testing successful and failed retrieval, and to demonstrate the basic layout of a response. The data returned in samples may not represent actual values that this feature will deliver.
NOTE: The D-U-N-S Number returned in the response will be a nine-digit zero-padded, numeric value.
{"CleanseAndStandardizeResponse": {
"TransactionDetail": {
"ServiceTransactionID": "Id-5432765822550200924a0500ca38e920-1",
"TransactionTimestamp": "2017-01-11T08:25:41"
},
"TransactionResult": {
"SeverityText": "Information",
"ResultID": "CM000",
"ResultText": "Success"
},
"CleanseAndStandardizeResponseDetail": {
"InquiryDetail": {
"OrganizationName": {"$": "Gorman Manufacturing"},
"Address": {
"CountryISOAlpha2Code": "US",
"TerritoryName": "CA"
}
},
"StandardizedName": {"OrganizationName": {"$": "Gorman Manufacturing"}},
"StandardizedAddress": {
"TerritoryAbbreviatedName": "CA",
"TerritoryName": "California",
"CountryISOAlpha2Code": "US",
"CountryName": "United States",
"DeliveryPointValidationDetail": {
"StatusValue": "No DPV Address",
"CMRAValue": "No DPV Address"
},
"AddressTypeValue": "Unknown",
"InexactAddressIndicator": false
}
}
}}
Response Codes & Error Handling
Successful service requests will return a CM000 response code in the TransactionResult ResultID field. Otherwise, one of the D&B Direct standard response codes will be returned.
This operation may return the following response codes: CM002, CM003, CM004, CM005, CM007, CM011, and SC001-SC009.
D&B Direct 2.0 API requests are provided on a metered basis; and may require entitlement prior to use in the production environment. In addition, a concurrency limit (QPS) is monitored to ensure that it is not exceeded. An error code will be returned in the event that a transaction is throttled.
Qualified usage (e.g., a successful response) is tracked and billed according to the terms & conditions of the customer's contract. The response codes CM000, CM010, PD002 and PD015 are considered successful. A built-in feature exists to prevent duplicate billing when multiple successful requests with the same criteria are submitted on the same calendar day (which is based on Eastern Standard Time [GMT-5]).
Business Elements
While D&B Direct uses a product canonical naming model in the request/response, many customers may be more familiar with the following business element labels.
| Name | Description |
|---|---|
| Delivery Point Validation CMRA | BR: Y - The address is a valid Commercial Mail Receiving Agency (CMRA). A CMRA is a private business that accepts mail delivery from the Postal Service for others (addressee), holds it for pickup (in most cases a private mailbox ("PMB") or re-mails it to another address with payment of new postage. (Example: “Mailboxes, Etc.”) N - The address is not a valid Commercial Mail Receiving Agency (CMRA). L - Submitted address is invalid, undeliverable and could not be identified by DPV. These are “decoy,” fantasy addresses. Blank - DPV cannot categorize the input address PCM XPath: //StandardizedAddress/ DeliveryPointValidationDetail/ CMRAValue |
| Delivery Point Validation STATUS | BR: Y - Submitted address is valid, including, if required for delivery, the secondary address: suite, room, floor or apartment #. This is equal to DSF Deliverability Indicator #1. N - Submitted address is invalid and possibly to definitely undeliverable. It might however, qualify for a ZIP+4. This is equal to DSF Deliverability Indicator #4 or higher or X. S - Secondary address invalid: submitted street address is valid, but the submitted secondary address - the suite, room, floor or apartment # -- required for delivery at this location, is incorrect. This address is possibly deliverable, at the letter carrier's option. This is equal to DSF Deliverability Indicator #2. D - Secondary address missing: submitted street address is valid, but the secondary address - the suite, room, floor or apartment # -- required for delivery at this location, is missing. This address is possibly deliverable, at the letter carrier's option. L - Submitted address is invalid, undeliverable and could not be identified by DPV. This is a fictitious address on the DPV file designed to identify mis-use of USPS data. Contact your DB rep. Blank - DPV cannot categorize the input address. PCM XPath: //StandardizedAddress/ DeliveryPointValidationDetail/ StatusValue |
| Standardized Address Address Type | PCM XPath: //StandardizedAddress/ AddressTypeValue |
| Standardized Address Business Name | Standardised Primary Name of the Business PCM XPath: //StandardizedName/ OrganizationName |
| Standardized Address Country/Market Code | PCM XPath: //StandardizedAddress/ CountryISOAlpha2Code |
| Standardized Address Country Name | PCM XPath: //StandardizedAddress/ CountryName |
| Standardized Address County | PCM XPath: //StandardizedAddress/ CountyName |
| Standardized Address Inexact Indicator | PCM XPath: //StandardizedAddress/ InexactAddressIndicator |
| Standardized Address Postal Code | Zip code from inquiry request PCM XPath: //StandardizedAddress/ PostalCode |
| Standardized Address Street | PCM XPath: //StandardizedAddress/ StreetAddressLine/ LineText |
| Standardized Address Territory | PCM XPath: //StandardizedAddress/ TerritoryName |
| Standardized Address Territory Abbreviated Name | PCM XPath: //StandardizedAddress/ TerritoryAbbreviatedName |
| Standardized Address Town Name | PCM XPath: //StandardizedAddress/ PrimaryTownName |
The preceding list is not presented in the order, nor manner, in which the information is packaged and delivered via the D&B Direct API. Legend: [C] = may be included in a Custom Data product; [M] = may be referenced by the Monitoring process; [M+] = Monitored using an aggregate or attribute XPath.
Feature Notes
When a multi-line address is provided (e.g. building number, street name and post office box in a single request), this feature will return the proper address for mailing purposes.
- © Dun & Bradstreet, Inc. 2019 – 2024. All rights reserved.