On-Demand Address Cleanse & Update
Also known as Cleanse and Standardize
|Product Code(s)||Not Applicable|
|5.0 Released On||July 10, 2015|
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.
- 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.
IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.
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.
The Company_CleanseAndStandardize data layer is available for businesses domiciled in the following countries:
|United States of America||US|
|Antigua & Barbuda||AG|
|British Virgin Islands||VG|
|Bonaire, Sint Eustatius And Saba||BQ|
|Sint Maarten (dutch)||SX|
|Saint Kitts & Nevis||KN|
|Trinidad And Tobago||TT|
|Turks And Caicos||TC|
|Benin, Peoples Republic of||BJ|
|Bosnia And Herzegovina||BA|
|Kampuchea (prev. Cambodia)||KH|
|Cape Verde, Republic of||CV|
|Central Africa Republic||CF|
|Chad, Republic of||TD|
|China, Peoples Republic of||CN|
|Congo Democratic Republic||CD|
|Turkish Republic of Northern Cyprus||XT|
|Guinea, Republic of||GN|
|Hong Kong SAR||HK|
|Ivory Coast/cote D'ivoire||CI|
|Korea, Republic of||KR|
|Papua New Guinea||PG|
|Saint Pierre Et Miquelon||PM|
|Sao Tome & Principe||ST|
|United Arab Emirates||AE|
|Holy See (vatican City State)||VA|
|Serbia & Montenegro||CS|
|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.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:com="http://services.dnb.com/CompanyServiceV2.0"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand="0" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:UsernameToken wsu:Id="UsernameToken-11"> <wsse:Username>MyUserName</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">MyPassword</wsse:Password> </wsse:UsernameToken> </wsse:Security> </soapenv:Header> <soapenv:Body> <com:CleanseAndStandardizeRequest ServiceVersionNumber="4.0"> <CleanseAndStandardizeRequestDetail> <InquiryDetail> <OrganizationName LanguageCode="39">Gorman Manufacturing</OrganizationName> <Address> <CountryISOAlpha2Code>US</CountryISOAlpha2Code> <TerritoryName>CA</TerritoryName> </Address> </InquiryDetail> </CleanseAndStandardizeRequestDetail> </com:CleanseAndStandardizeRequest> </soapenv:Body> </soapenv:Envelope>
|CleanseAndStandardizeRequest @ServiceVersionNumber||Attribute, Optional|
|CleanseAndStandardizeRequest @schemaLocation||Attribute, Optional|
|CleanseAndStandardizeRequest. TransactionDetail||Aggregate, Optional|
|CleanseAndStandardizeRequest. TransactionDetail. ApplicationTransactionID||Element, string up to 64 chars., Optional|
Unique Transaction ID of the request generated by the service
|CleanseAndStandardizeRequest. TransactionDetail. TransactionTimestamp||Element, Optional|
The date and time when this request was created.
|CleanseAndStandardizeRequest. TransactionDetail. SubmittingOfficeID||Element, string up to 64 chars., Optional|
A number that identifies the system or the software application from where this request originated.
|End: CleanseAndStandardizeRequest. TransactionDetail||Aggregate, Optional|
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail||Aggregate, Required|
Records the name and/or address data provided by the customer to be corrected and/or standardized in real time.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail||Aggregate, Required|
Records the name and/or address data for an organization provided by the customer to be corrected and/or standardized in real time.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. OrganizationName||Element, string up to 256 chars., Optional|
Text recording the name of the inquired organization by which it is known / identified.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. OrganizationName @LanguageCode||Attribute, Optional|
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. OrganizationName @WritingScriptISOAlpha4Code||Attribute, Optional|
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address||Aggregate, Required|
Records the address details of an organization. An address is the designation of a place where a subject can be located or may be communicated with.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address. StreetAddressLine||Aggregate, Optional|
An entry loop which can repeat multiple times to allow the recording of several street address lines of Inquired Business.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address. StreetAddressLine. LineText||Element, string up to 240 chars., Required|
|End: CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address. StreetAddressLine||Aggregate, Optional|
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address. PrimaryTownName||Element, string up to 64 chars., Optional|
The name of the town or city recognized by the Postal Authority for delivering mail.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address. CountryISOAlpha2Code||Element, string at least 2 chars. up to 2 chars., Required|
The two-letter country code, defined in the ISO 3166-1 scheme published by International Organization for Standardization (ISO), identifying the country for this address.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address. CountyName||Element, 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.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address. TerritoryName||Element, 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.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address. PostalCode||Element, 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.
|End: CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail. Address||Aggregate, Required|
|End: CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryDetail||Aggregate, Optional|
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryReferenceDetail||Aggregate, Optional|
Records data that allows the customer to specify information to be linked to the request in order to support subsequent order reconciliation.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryReferenceDetail. CustomerReferenceText||Element, string at least 1 chars. up to 240 chars., Optional|
A freeform reference string provided by the customer to be linked to the product in order to support subsequent order reconciliation.
|CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryReferenceDetail. CustomerBillingEndorsementText|
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.
|End: CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail. InquiryReferenceDetail||Aggregate, Optional|
|End: CleanseAndStandardizeRequest. CleanseAndStandardizeRequestDetail||Aggregate, Required|
|End: CleanseAndStandardizeRequest||Aggregate, Required|
Use the following endpoint with the downloadable WSDL to request this feature.
This operation will return a static set of results in the D&B Direct test environment (sandbox), regardless of the request parameters.
The following is a list of the possible data fields returned by this operation in the XML 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.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <com:CleanseAndStandardizeResponse ServiceVersionNumber="2" xmlns:com="http://services.dnb.com/CompanyServiceV2.0"> <TransactionDetail> <ServiceTransactionID>Id-a9ebf14551de8d9f023b742e-1</ServiceTransactionID> <TransactionTimestamp>2013-07-11T06:49:03</TransactionTimestamp> </TransactionDetail> <TransactionResult> <SeverityText>Information</SeverityText> <ResultID>CM000</ResultID> <ResultText>Success</ResultText> </TransactionResult> <CleanseAndStandardizeResponseDetail> <InquiryDetail> <OrganizationName LanguageCode="39">Gorman Manufacturing</OrganizationName> <Address> <CountryISOAlpha2Code>US</CountryISOAlpha2Code> <TerritoryName>CA</TerritoryName> </Address> </InquiryDetail> <StandardizedName> <OrganizationName>Gorman Manufacturing</OrganizationName> </StandardizedName> <StandardizedAddress> <TerritoryAbbreviatedName>CA</TerritoryAbbreviatedName> <TerritoryName>California</TerritoryName> <CountryISOAlpha2Code>US</CountryISOAlpha2Code> <CountryName>United States</CountryName> <DeliveryPointValidationDetail> <StatusValue>No DPV Address</StatusValue> <CMRAValue>No DPV Address</CMRAValue> </DeliveryPointValidationDetail> <AddressTypeValue>Unknown</AddressTypeValue> <InexactAddressIndicator>false</InexactAddressIndicator> </StandardizedAddress> </CleanseAndStandardizeResponseDetail> </com:CleanseAndStandardizeResponse> </soapenv:Body> </soapenv:Envelope>
NOTE: There may be additional request and/or response elements specified in the WSDL that are not applicable for D&B Direct customers. Data elements that are not listed on this page are currently unused by this operation.
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]).
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.
|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 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.
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.