Dun and Bradstreet

On this page

• Before you begin
• Add D&B enricher
• Matching behavior
• Property mappings
• Properties from D&B enricher

This article explains how to configure the D&B (Dun & Bradstreet) enricher. The enricher uses D&B Direct+ Identity Resolution APIs to enrich organization golden records with business identity, address, corporate-linkage, contact, industry, financial, and D-U-N-S information.

The enricher uses the following D&B API paths, relative to the configured D&B Base URL:

• data/duns/{dunsNumber} for direct D-U-N-S lookups.
• match/cleanseMatch for multiple identity-resolution candidates.
• match/extendedMatch for the best match and the requested product data.

Before you begin

You need D&B Direct+ credentials and access to the data product or data blocks that you intend to request. For information about obtaining and using these values, see the D&B Direct+ documentation. Obtain the authentication URL, API key, API secret, authentication request body, base URL, and either:

• a Version ID and Product ID; or
• one or more Block IDs.

For identity resolution without a D-U-N-S number, golden records must contain both an organization name and a two-letter ISO country code. The enricher can also use the address, registration number, telephone number, website, and email address to improve the match request.

Add D&B enricher

To add the D&B enricher

1. On the navigation pane, go to Preparation > Enrich. Then, select Add Enricher.

2. On the Choose Enricher tab, select DnB, and then select Next.

3. On the Configure tab, provide the following details.

   Authentication

   • Auth URL – the D&B endpoint used to obtain an access token. The default value is https://plus.dnb.com/v2/token.
   • API Key – the D&B API key. The enricher sends this value with the API secret as HTTP Basic authentication when requesting an access token. For example: <D&B API key>.
   • API Secret – the D&B API secret. For example: <D&B API secret>. Do not enter this value in documentation, source control, or screenshots.
   • Auth Request Body – the JSON request body required by the D&B authentication endpoint. The default value is {"grant_type" : "client_credentials"}.
   • D&B Base URL – the base URL for the D&B Direct+ APIs. Use the base URL supplied by D&B for your account and API product. For example: https://<your-D&B-Direct+-API-base-URL>/.

   Matching and data retrieval

   • Accepted Business Domain – the business domain that defines the golden records to enrich. For example, /Organization.
   • Identity Resolution API – choose one of the following options:
     • Cleanse Match returns multiple match candidates from the match/cleanseMatch endpoint.
     • Extended Match returns the best match and requested product data from the match/extendedMatch endpoint.
   • Get Data Using Matches DUNS – when enabled, retrieves organization data by using the D-U-N-S number returned by a match candidate.
   • Include Last API Call Details – when enabled, writes the timestamp, status code, and error message from the last D&B API call to the enriched record. This is useful when a request cannot return organization data.
   • Match and Append versionId and Match and Append productId – the D&B version and product identifiers. Provide both values together.
   • Match and Append blockIDs – the D&B data block identifier or identifiers to return. Use this instead of the Version ID and Product ID when your D&B product is configured by blocks.

   Vocabulary keys

   • DUNS Vocabulary Key – the D-U-N-S number. When present, the enricher performs a direct D-U-N-S lookup.
   • Organization Name Vocabulary Key and Organization Country Code Vocabulary Key – the organization name and ISO Alpha-2 country code. Both are required when no D-U-N-S number is available.
   • Optionally provide vocabulary keys for Registration Number, Organization Street Address Line 1, Organization Street Address Line 2, Organization Postal Code, Organization Address Locality, Organization Address County, Organization Address Region, Organization Telephone Number, Organization URL, and Organization Email. These values are sent with the identity-resolution request when available.

   Optional D&B request parameters

   • Customer Billing Endorsement – a reference used during billing.
   • Candidate Maximum Quantity – the maximum number of match candidates to return; the default is 10 and the allowed range is 1 through 100.
   • Confidence Lower Level Threshold Value – the minimum D&B match confidence level; the default is 4 and the allowed range is 1 through 10.
   • Exclusion Criteria – comma-separated criteria for excluding candidates, for example ExcludeNonHeadQuarters,ExcludeNonMarketable,ExcludeOutofBusiness.
   • Is Cleanse and Standardize Information Required – includes D&B cleanse and standardize information in the response.
   • Trade Up – returns the headquarters D-U-N-S number when the requested organization is a branch. For example, hq.
   • Order Reason and Customer Reference 1 through Customer Reference 5 – optional D&B order and reconciliation references.
   • Industry Code Types – comma-separated D&B TypeDnBCode values that identify the industry codes to add to the result. For example, 19295,37788.
   • Registration Number Types – comma-separated D&B TypeDnBCode values that identify the registration numbers to add to the result. For example, 12897,12444.
   • Property Mappings – optional custom mappings from the D&B JSON response. For details and examples, see Property mappings.

4. Select Test Connection to verify the configuration, and then select Add.

The D&B enricher is added with active status. It enriches matching golden records when they are processed or when you trigger external enrichment.

After adding the enricher, you can change its Settings to set a display name, data description, and source quality, or update the connection values under Authentication.

Matching behavior

The enricher first checks for a D-U-N-S number. If one is available, it calls data/duns/{dunsNumber} and returns the organization data directly.

If no D-U-N-S number is available, the enricher requires an organization name and ISO Alpha-2 country code. It calls the selected Identity Resolution API and includes any optional configured input values. The request must also contain either a Version ID and Product ID pair, or Block IDs.

When Get Data Using Matches DUNS is enabled, the enricher uses the D-U-N-S number from the D&B match candidate to make a second direct lookup. Otherwise, it enriches the record from the selected identity-resolution response.

Property mappings

Use Property Mappings when the standard D&B vocabulary does not expose a value that you need, or when you want to add a value to a property with a specific name. Each mapping creates or updates the CluedIn property named on the left of the equals sign.

Enter one mapping on each line using this format:

Property=JSONPath

For example, this mapping adds the value of organization.email from the D&B response to an Email property:

Email=$.organization.email

You can use JSONPath to retrieve values nested in the response and to filter arrays. For example, D&B registration numbers include a typeDnBCode. The following mapping finds the registration number whose type code is 2080 and writes it to ValueAddedTaxNumberFR:

ValueAddedTaxNumberFR=$.organization.registrationNumbers[?(@.typeDnBCode == 2080)].registrationNumber

Use the same pattern for other country-specific registration-number types, replacing both the destination property name and the D&B type code:

ValueAddedTaxNumberBE=$.organization.registrationNumbers[?(@.typeDnBCode == 999)].registrationNumber
ValueAddedTaxNumberCZ=$.organization.registrationNumbers[?(@.typeDnBCode == 1315)].registrationNumber
ValueAddedTaxNumberHU=$.organization.registrationNumbers[?(@.typeDnBCode == 36137)].registrationNumber

To collect all values from an array, use [*]. The enricher combines the matching values into a comma-separated string. For example:

RegistrationNumbers=$.organization.registrationNumbers[*].registrationNumber

Property mappings are evaluated against the JSON returned by the D&B API. Make sure that your D&B product or selected data blocks return the path you map. If a path has no value, the enricher does not add that mapped property. Invalid mappings are ignored and are recorded as warnings in the application logs.

Properties from D&B enricher

The D&B enricher adds properties with the DnB vocabulary prefix. The exact data returned depends on your D&B product and selected data blocks.

Property group	Example vocabulary keys
Business identity	DnB.Duns, DnB.PrimaryBusinessName, DnB.BusinessEntityTypeDnbCode, DnB.BusinessEntityTypeDescription
Match quality	DnB.MatchConfidenceCode
Corporate linkage	DnB.DomesticUltimateDuns, DnB.GlobalUltimateDuns, DnB.ParentDuns, DnB.HeadQuarterDuns, DnB.HierarchyLevel
Address and contact	DnB.PrimaryAddressCountry, DnB.PrimaryAddressLocality, DnB.PrimaryAddressPostalCode, DnB.PrimaryAddressStreetLine1, DnB.WebsiteUrl, DnB.Telephone, DnB.Fax
Status and identifiers	DnB.OperatingStatusCode, DnB.OperatingStatusDescription, DnB.DunsControlStatusIsMarketable, DnB.RegistrationNumber2
Organization scale	DnB.NumberOfEmployees, DnB.YearlyRevenue, DnB.GlobalUltimateNumberOfEmployees, DnB.DomesticUltimateNumberOfEmployees
Market data	DnB.StockExchangeTickerName, DnB.StockExchangeName, DnB.StockExchangeCountryCode, DnB.TradeStyleNames
Selected industry codes (Optional)	DnB.industry.{index}.code, DnB.industry.{index}.description, DnB.industry.{index}.typeDnBCode
Selected registration numbers (Optional)	DnB.registrationNumbers.{index}.registrationNumber, DnB.registrationNumbers.{index}.typeDescription, DnB.registrationNumbers.{index}.typeDnBCode
API-call diagnostics (Optional)	DnB.LastApiCallTimestamp, DnB.LastApiCallStatusCode, DnB.LastApiCallErrorMessage

Use the integrations filter on the Properties page to find properties added by the D&B enricher. To review a particular enrichment, open the relevant data part on the golden record’s History page.