---
title: Dun and Bradstreet
url: https://documentation.cluedin.net/govern/enrichment/dnb
content_type: reference
section: Govern & improve > Enrichment
---

# Dun and Bradstreet

> reference: Facts, options, APIs.

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](https://directplus.documentation.dnb.com/). 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**.

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

1. 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](#property-mappings).

1. 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:

```text
Property=JSONPath
```

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

```text
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`:

```text
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:

```text
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:

```text
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.

Up: [Enrichment](https://documentation.cluedin.net/govern/enrichment.md)