Cookies Settings

Loading

dnb-logo
Direct 2.0
Collapse

D&B Direct Data Primer

This Microsoft Exceltm spreadsheet identifies the business elements and data fields delivered by each D&B Data product, along with the data types and definitions.

Latest Edition

Updates to the Data Primer are included as part of the Release Notes.

Download the Data Primer
Last updated on March 05, 2021

Primer Tabs

Data Layers Tab (was "Products")

This tab lists D&B Direct product codes, along with the data layer name, level and service (required for SOAP implementations). The table also maps the products to similar offerings from D&B Direct 1.x and the D&B Data Integration Toolkit.

Business Elements Tab

D&B Direct API services supply information in standardized Data Fields, each of which may deliver multiple Business Elements. This tab lists business element names and the product packages that they are included in, along with the corresponding data field (a.k.a. XPATH). The column headings are D&B Direct product codes (refer to the Products tab for product names).

In an effort to improve efficiency and reduce redundancy, some data fields in the D&B Direct API deliver multiple business elements. When these scenarios occur, developers will need to inspect adjacent fields and/or attributes to identify specific business elements. Details...

NOTE: D&B Direct financial data layers (FIN_HGLT, FIN_ST_PLUS) return complete statements, of which there are close to 6,000 possible row values. These are dependent on how each company prepares/files their statements. Only the most common items were added to the documentation (and Data Primer).

Product Request Tab (was "Parameters")

A table listing input parameters across the product data layers.

Product Response Tab (was "Data Fields")

A table listing XPATH's referenced by D&B Direct products, along with the data type, occurrences, and definition. Each data field is identified as either an aggregate, attribute or element.

Feature Request Tab

A table listing input parameters across the match, search, investigation and other features.

Feature Response Tab

A table listing response fields across the match, search, investigation and other features.

Data Exchange Tab

A table listing response fields from partners participating in the D&B Data Exchange.

Country Chart Tab

A table listing available country names and codes mapped to each D&B Direct product and report. The column headings are D&B Direct product codes (refer to the Products tab for product names). Included is a mapping to the country codes used by D&B Direct 1.x and the D&B Worldbase-based products.

Documentation vs. Data Primer

While we make every effort to ensure the contents of the Data Primer are reflected in the online documentation, there may be times when a lag occurs. The Data Primer is ALWAYS updated prior to the field listings on documentation pages.

There are also some intentional differences between the Data Primer and product overview pages (a.k.a. "business element" pages), where the following types of items will NOT appear:

  • REPEATING ITEMS: customers who are familiar with some of D&B's other products may be used to seeing enumerated fields, and we include some of these in the Data Primer to help the developer understand how these are delivered; however, to reduce the size of the online documentation these are not displayed. (e.g. "Trade Style (2)", "Secondary SIC (4)")
  • ARRAY COUNTERS: these elements are delivered with the responses to allow developers to reference specific occurrences of an aggregate (e.g. "*.DisplaySequence") and are only relevant within a given response.
  • SUPPLEMENTAL ATTRIBUTES: there are some occurrences where an element is included in the Data Primer Product Response tab; however, it doesn't introduce new data, but rather helps describe/identify the contents of another element of aggregate. These are typically names *TypeText.
  • STANDARD ELEMENTS: as mentioned on the product overview pages, a set of elements (e.g. name, address) are included on ALL OrderProduct responses, and as a result do not appear in the business element listings.
  • NON-DELIVERABLE or NO LONGER VENDIBLE: due to the nature of SOAP implementations (which are bound to a WSDL), there may be data fields that continue to appear on the Data Primer Product Response tab between API releases, which are no longer included on the product overview pages. These fields either no longer deliver any/current data and/or D&B has decided the field will be removed from the product, and will drop out of the Data Primer in a future update.

Business Element Rules

In an effort to improve efficiency and reduce redundancy, some data fields in the D&B Direct API deliver multiple business elements. When these scenarios occur, developers will need to inspect adjacent fields and/or attributes to identify specific business elements. Three additional columns have been added to the latest version of the D&B Direct API Data Primer to provide these additional details. They include the Rule Field, Type and Value.

Rule Field

This column will include the names of one or more (comma separated) neighboring fields that need to be inspected. In some cases, these fields may be one level above the data field. They may be an attribute of the data field, another element, or an attribute of another element.

Example: "StatementItem@DNBCodeValue, FinancialStatementToDate, FinancialPeriodDuration"

Rule Type

This column explains what type of information will be contained in the value column, which may include "SCoTS" (a D&B reference code), "value" or "as received."

When the type is "SCoTS" or "value", the developer should inspect the corresponding neighboring field for the value.

When the type is "as received", the developer should keep track of the sequence of repeating elements and match against the value.

Example: "SCoTS, as received, value"

Rule Value

This column provides the information that a developer should test the neighboring fields for. Values which are enclosed in {braces} are abstract types.

The abstract type of {blank} indicates the developer should test to see if the neighboring field is blank (or null).

The abstract types of {latest} and {previous} refer to financial statements. The developer should keep track of the values in the neighboring fields to determine which financial statement is the {latest} and which is the {previous}. Financial statement data is returned in reverse-chronological order.

Example: "21958, {latest}, P1Y"

Sample Rule

Here is a snippet of a JSON response from the Financial Product Service:

              "StatementHeaderDetails":               {
                "FinancialStatementToDate": {"$": "2012"},
                "CurrencyISOAlpha3Code": "USD",
                "UnitOfSizeText": {"$": "Million"},
                "FinancialPeriodDuration": "P1Y"
              },
              "BalanceSheet":               {
                "Assets":                 {
                  "LongTermAssets": {"StatementItem":                   [
                                        {
                      "@DNBCodeValue": 5573,
                      "ItemDescriptionText": {"$": "Tangible fixed assets"},
                      "ItemAmount": {"$": 13997}
                    },
                                        {
                      "@DNBCodeValue": 21958,
                      "ItemDescriptionText": {"$": "Other Long Term Assets"},
                      "ItemAmount": {"$": 55783}
                    }
                  ]}
                },

Here is how to locate the "Other Long Term Assets" value from the most recent annual balance sheet:

Rule Field: "StatementItem@DNBCodeValue, FinancialStatementToDate, FinancialPeriodDuration"

Rule Type: "SCoTS, as received, value"

Rule Value: "21958, {latest}, P1Y"

1: Inspect the @DNBCodeValue of StatementItem data fields to locate the SCoTS code of 21958.

2. Track the sequence of FinancialStatementToDate fields in the statement header to determine which is the {latest}. In this case, it is 2012.

3. Inspect the FinancialPeriodDuration in the statement header for the value of "P1Y" to verify it is an annual statement.

In this example, the business element value is 55783.