D&B Data Blocks Data File Delivery

Overview

A Data Block is a logical, topic-based grouping of data elements from the Dun & Bradstreet Data Cloud. It is a modern, best-in-class method of serving data in a simple, standardized, and flexible way. Clients can 'stack' data blocks together to customize the data and insights they require to address any use case across their business. Customer's specific combination of Data Blocks are delivered via API, flat files, or a combination. This guide explains the process for interacting with the D&B Data Cloud to receive Data Blocks via Data Files.

Here is a look at the end-to-end process:
Batch_Process

There are two main operations available as part of data file delivery of D&B Data Blocks:

  1. Entity Resolution
  2. Data Block Enrichment

Entity Resolution

D&B Entity Resolution uses input criteria to find the best candidates in its extensive database of entities. It uses proprietary algorithms to identify the best matches and returns those matches with detailed information about what criteria was used to find the match.
When utilizing Entity Resolution via data files, an input file is submitted containing input criteria. Each record from the input file is evaluated and the single most likely match for the given criteria is identified. If a match is found, the response information will be provided in the Entity Resolution data file.

Data Block Enrichment

D&B Enrichment offers data from the D&B Data Cloud in packages termed Data Blocks.
When utilizing Enrichment via data files, output files will be created containing all the Data Elements in the selected Data Blocks.

Data File Profile Configuration

The chosen data file operations and configurations are saved as a Data File Profile, allowing for new input files to be submitted and processed as often as needed utilizing the saved configurations.
The following configuration selections should be provided by the customer to the D&B Delivery Consultant for creating the Data File Profile.

Configuration Description
Domain The area of the client's business where this data will be leveraged. Options are limited to only those Domains the customer has contracted for. Domains include:
  • Sales & Marketing
  • Finance
  • Supply
  • Compliance
  • Enterprise Master Data
Record Type How the client will use this data. Options are limited to only those Record Types the customer has contracted for. Record Types include:
  • Full Domain Use
  • Master Data Use
  • Analytical Use
Profile Name A name used to uniquely denote this batch profile. Must be unique per customer. Cannot include spaces or special characters other than an underscore (_) or hyphen (-).
Profile Description Free text description. Examples include: what the Profile will be used for, what business function, what team, etc.
Process Type The operation(s) to be performed on the customer input files submitted for this Profile. Options include:
  • Entity Resolution only (Match)
  • Entity Resolution + Enrichment (MatchEnrich)
  • Enrichment only (Enrich)
Input File Format The format of the customer's input file. Options include:
  • Flat file
  • JSON
Input Column Delimiter The delimiter in the customer input file. Does not apply to JSON files. Options include:
  • pipe (|)
  • comma (,)
Trade Up Applies to Enrichment. This will return information for the headquarters when the matched organization is a branch. Options include:
  • Yes
  • No
Data Block(s) and Level The Data Block(s) Level to be appended in the Enrichment operation. Options are limited to only those Data Block(s) Level the customer has contracted for.
Match Confidence Code Filter Applies to Entity Resolution. A numeric value from 1 (low) up to 10 (high) indicating the required level of certainty at which a possible candidate should be included in the result set.
Output File Format The format to create output files in. Options include:
  • Flat file
  • JSON
Output Column Delimiter The delimiter in the output file(s). Does not apply to JSON files. Options include:
  • pipe (|)
  • comma (,)
Output Compression Format This is the compression format of the D&B Data Block Data File(s) that are returned. Options include:
  • GZIP
  • ZIP
File Segregation The output file splitting. Options include:
  • DataBlockLevel (The output files are split into a separate file for each selected Data Block. Each file will contain the customer input data and the match results along with the enriched data block elements. This is the recommended option for most customers based on the large volume of elements and data.)
  • None (The output data will be combined into a single output file.)
German Reason Code This reason code is required when enriching D&B Data Blocks on organizations domiciled in Germany. Reason Codes include:
  • Credit Decision
  • Credit Check – Intended Business Connection
  • Credit Check – Ongoing Business Connection
  • Debt Collection
  • Commercial Credit Insurance
  • Insurance Contract
  • Lease Agreement
  • Rental Agreement

Creating An Input File

There are two types of Input Files, depending on which operations are being invoked.

Operation to be performed Input File type that should be submitted
  • Entity Resolution only
  • Entity Resolution + Enrichment
Entity Resolution Input File - contains the information about the subject companies required by D&B Entity Resolution for matching to companies in the D&B Data Cloud
  • Enrichment only
Enrichment Input File - contain the list of D-U-N-S Numbers to be enriched with D&B Data Blocks

Entity Resolution Input File

The input file should contain information about the subject companies for matching to the D&B Data Cloud. The more criteria provided for each subject company, the greater the chance for a high quality match.

The following input criteria are supported:

Input Criteria Column Header for Input File Data Type Required Example Description
Business Name organization.primaryNames[0].name string false string used to search for entities Up to 240 characters used to find the entity by its primary name, tradestyle names, or former names.
This value is required for "Name and Address" Lookup
Street Address Line1 organization.primaryAddresses[0].streetAddress.line1 string false street address Up to 70 characters of the first line of the entity's street address.
This value is required for "Name and Address" Lookup.
Street Address Line2 organization.primaryAddresses[0].streetAddress.line2 string false street address line 2 Up to 70 characters of the second line of the entity's street address.
Address Locality organization.primaryAddresses[0].addressLocality.name string false short hills 1 to 50 characters that identifies the city, town, township, village, borough, etc. where the entity is located.
Address Region organization.primaryAddresses[0].addressRegion.name string false NJ The name of the locally governed area that forms part of a centrally governed nation to identify where the address is located.
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.
If country is US or CA, the Region must be the 2-character abbreviation. For other countries, it can be up to 64 characters.
Postal Code organization.primaryAddresses[0].postalCode string false 94536 Up to 10 characters of the identifier used by the local country's postal authority to identify where the address is located.
This value is required for Postal Code Lookup.
Country ISO Alpha 2 Code organization.primaryAddresses[0].addressCountry.isoAlpha2Code string true US The 2-letter country code defined by the International Organization for Standardization (ISO) ISO 3166-1 scheme identifying the country of the entity.
This value is required for all requests that do not contain a D-U-N-S Number.
Address County organization.primaryAddresses[0].addressCounty.name string false Essex The name of the county in which this address is located.
Telephone Number organization.telephone.telephoneNumber string false 5555555555 The sequence of digits used for voice communication with the entity. This sequence of digits includes the area code or city code and domestic dialing code.
Valid values:
  • For Asian matching, up to 16 characters.
  • For non-Asian matching, up to 32 characters./li>
This value is required for Telephone Number Lookup.
URL organization.url string false www.dnb.com A URL used to identify an entity by its web domain.
Email Address organization.email string false jones@dnb.com An email address used to identify an entity by its email domain.
D-U-N-S Number organization.duns string false 804735132 A 9-character numeric string identifying the entity by its Dun & Bradstreet D-U-N-S number.
Business Registration Number organization.registrationNumber string false 11514917000120 The number assigned by an external body or by Dun & Bradstreet that either uniquely identifies or helps to identify an organization.
This value is required for Registration Lookup.
The Country ISO Alpha 2 Code must be included if providing Business Registration Number. A Registration lookup is triggered first when the request includes a Business Registration Number; if the resulting candidate has a low confidence code then a match will be performed based on the name or address provided.
Business Registration Number Type organization.registrationTypeDnBCode integer false 1340 A unique code assigned by Dun & Bradstreet to identify the type of registration number.
Refer to Reference code table "7 [Registration Number Type]" for all possible values.
This is not required when submitting a Business Registration Number but recommended and will increase the match accuracy in the event two number-assigning bodies use overlapping numbers.
Customer Reference customerReference[0] string false internal unique identifier A free form reference string provided by the customer to be linked to the request and included in the response. Up to 5 customerReference values may be submitted in the request (e.g., customerReference[0], customerReference[1], customerReference[2], …).

Sample Input Data

organization.primaryNames[0].name,organization.primaryAddresses[0].streetAddress.line1,organization.primaryAddresses[0].addressLocality.name,organization.primaryAddresses[0].addressRegion.name,organization.primaryAddresses[0].addressCountry.isoAlpha2Code
Company Name,Address Line 1,Locality (city),Region (state),US
Company Name,Address Line 1,Locality (city),Region (state),US
Company Name,Address Line 1,Locality (city),Region (state),US
Company Name,Address Line 1,Locality (city),Region (state),US
Company Name,Address Line 1,Locality (city),Region (state),US
Select File Format below and click Download button to download sample files that can be used as templates for creating new input files:
Download

Enrichment Input File

The input file for enrichment-only should contain the list of D-U-N-S Numbers to be enriched with D&B Data Blocks.
The following input criteria are supported:

Input Criteria Column Header for Input File Data Type Required Example Description
D-U-N-S Number Do not include a header record string true 804735132 A 9-character numeric string identifying the entity by its Dun & Bradstreet D-U-N-S number.

Sample Input Data

081556463
884114609
150483782
137375200
964652973
Click here to download a sample file that can be used as a template for creating a new input file:
Download Enrichment Input File template

Input File Specifications

Category Entity Resolution Enrichment
File type Supported file types:
  • delimited text file (.txt)
  • comma-separate-value file (.csv)
Supported file types:
  • delimited text file (.txt)
File Format Supported file formats:
  • Flat File
  • JSON
Supported file formats:
  • Flat File
  • JSON
Column delimiter Supported column delimiters:
  • pipe (|)
  • comma (,)
Supported column delimiters:
  • pipe (|)
  • comma (,)
Row delimiter Supported row delimiters:
  • carriage return line feed (CRLF)
  • line feed (LF)
Supported row delimiters:
  • carriage return line feed (CRLF)
  • line feed (LF)
Containing strings Double-quotes can be used for containing text strings, but this is not required; use consecutive double-quotes ("") or backslash (\) to escape the double-quotes when you have a string containing double-quotes Not applicable
Header row A header row is required and header names must exactly match the specified names Do not include a header record
Column order The order of columns does not matter Not applicable
Character encoding Supported encodings:
  • ASCII
  • UTF-8
Supported encodings:
  • ASCII
  • UTF-8
File compression Supported compression types:
  • GZIP
  • ZIP
Supported compression types:
  • GZIP
  • ZIP
File naming File names must follow this naming convention:
Batch.<profileName>.<customerReferenceText>.<extension>
  • profileName - this string must exactly match the unique Profile Name that was assigned when the associated Data File Profile was created by the D&B Delivery Consultant
  • customerReferenceText - this is free text for the customer to populate as needed; the same text will be included in the output file(s) as a reference for the customer to associate the input and output files
For example: Batch.VendorListProfile.MyApril2020List.csv
  • Each new file submission must have a unique name
  • Cannot include spaces or special characters other than an underscore (_) or hyphen (-)

Tips on Creating an Input File

  • Include a datestamp in the name of your input file within the "customerReferenceText" to make it unique and help associate input and output files. For example, Batch.VendorListProfile.20200401.csv
  • Database software and other applications typically offer the option to export data into delimited text files. For example, Microsoft Excel has the option to Save As CSV UTF-8 (Comma delimited) (*.csv).

Submitting Input Files for Processing

Client Input Files should be submitted via the D&B SafeTransPort (STP) application. The files should be uploaded to the "puts" folder. The D&B system will automatically detect the Input File and read the Profile Name from within the file name to determine the correct Data File Profile to invoke when processing the file.

The file must follow this naming convention:

Batch.<profileName>.<customerReferenceText>.<extension>

  • profileName - this string must exactly match the unique Profile Name that was assigned when the associated Data File Profile was created by the D&B Delivery Consultant
  • customerReferenceText - this is free text for the customer to populate as needed; the same text will be included in the output file(s) as a reference for the customer to associate the input and output files
For example: Batch.VendorListProfile.MyApril2020List.csv

Retrieving Output Data Files

Data Block output files will be made available via D&B SafeTransPort (STP), located in the "gets" folder.

The file naming convention is:
Batch.<profileName>.<customerReferenceText>-<dataBlockName>_<fileNumberWhenSplittingFiles>_<totalFilesWhenSplitting>.<fileExtension>.<compressionFormatExtension>

Example file names:
For an input file named

  • Batch.myProfileName.myReferenceText-companyinfo_L3_v1_1_1.csv.gz
and if this output file was very large requiring it to be split into two files, then the file names would be
  • Batch.myProfileName.myReferenceText-companyinfo_L3_v1_1_2.csv.gz
  • Batch.myProfileName.myReferenceText-companyinfo_L3_v1_2_2.csv.gz

Understanding the Output Files

Identifying the Data Block

The Data Block name and level will be in the file name. In this example, the file contains "Company Information Level 1":

  • Batch.myProfileName.myReferenceText-companyinfo_L1_v1_1_1.csv
Understanding the content

The first field is always the D&B DUNS Number, our unique identifier. The last field is always the Sequence Number, which is the order of rows submitted in the customer input file.

Files contain two or three sections depending on the type of job:

Section How to identify Example fields
1. Client Input fields - these are the fields and data the customer provided in the input file Data elements beginning with "inquiryDetail."
  • inquiryDetail.organization.primaryNames[0].name
  • inquiryDetail.organization.primaryAddresses[0].addressCountry.isoAlpha2Code
2. Company Entity Resolution elements - these elements show how the input data matched to the D&B data Data elements beginning with "matchData." and "result[0]."
  • matchData.matchCandidates[0].matchQualityInformation.confidenceCode
  • matchData.matchCandidates[0].matchQualityInformation.matchGrade
3. Enriched Data Block elements - these are the purchased data block elements Data elements beginning with "enrichData."
  • enrichData.organization.primaryName
  • enrichData.organization.websiteAddress[0].url

Reference the Data Dictionary for definitions of the Data Block elements.
Option 1 (Using Excel Macros):

  1. Download the Excel file
  2. Enable the Macros at the top of the Excel file, if it is not enabled
    Macros

  3. Click on the button "Filter Data Blocks & Packets" and select the Data Block and Level you are interested in
    MacrosFilter

  4. Results will be shown once the progress is 100% complete
    MacrosFilterProgress

  5. Column D "JSON PATH" contains the field headers in the output files
    MacrosResults

  6. Click on the button "Export Filtered Data" to generate new Excel file with only the "JSON PATH" applicable for the Data Block and Level selected
    MacrosExport

  7. Click on the button "Show All" to clear the Macros filter and show all the "JSON PATH"

Option 2 (Manual Filtering):
  1. Download the Excel file
  2. Scroll right to find the Data Block and Level you are interested in
    DataBlock

  3. Filter on "Y"
    Filter

  4. Column D "JSON PATH" contains the field headers in the output files
    JSONPath

File Layout

Data Block files have a dynamic layout.

  • Files will include any and all data block elements where data is available for the customer's list of requested DUNS
  • Files will not include any elements where data is not available for the customer's list of requested DUNS
  • This behavior mimics pulling D&B data via API

Scenarios include:

  1. An element can have a variable number of values
    1. E.g., if the list of DUNS in a customer's output file have up to 3 Trade Style Names available, then we will include 3 Trade Style Name columns
    2. E.g., if the list of DUNS in a customer's output file only have 1 Trade Style Name available, then we will only include 1 Trade Style Name column
  2. Elements are only included if there is data
    1. E.g., if D&B does not have a non-English version of addresses for any DUNS in a file, then multilingualPrimaryAddress fields will not be included in the file

Dynamic layout benefits:

  • Customers seamlessly receive new data elements as D&B makes them available rather than waiting for a new version of a fixed layout that would require an upgrade
  • Customers receive all values we have for a given data element rather than being capped at a fixed number
  • Rolling out new data elements over time will not break customers' automated processes
  • Consistency with D&B Direct+ API delivery: dynamic file layouts mimic the behavior of pulling data from the APIs and provides consistency for customers who leverage both File and API delivery, or who migrate from one to the other
  • Avoids wasted space in files by not including completely blank columns and "filler" fields

Key points to understand:

  • The position and presence of columns in output files may change from delivery to delivery
  • The names of columns will never change and will always be unique
  • Column widths are always variable length depending on the data and are never fixed-width
  • Therefore, customers should map the files based on the column names and not the position in the file

Data Element Arrays

Some D&B data elements have many values for a single company. Data Block files will include as many of these values as we have available for a given company.

Examples:

  1. The data element "industryCodes" may have >20 values for a company. These values will be placed in columns industryCodes[0], industryCodes[1], industryCodes[2], ...
  2. The data element "stockExchanges" will repeat for every exchange a company is listed on.

Array benefits:
  • Customers will receive all the information D&B has on a company.
  • In the scenario of industryCodes, some customers may care more about one industry standard than another. Data Blocks will include as many standards as D&B maintains.

Data element arrays typically include multiple columns for a single value, such as:
  • D&B code
  • Description
  • Type
  • Priority
  • Other descriptors or identifiers

For example, "industryCodes" will show the following columns for the first industry code listed for a company:
Field name Value
enrichData.organization.industryCodes[0].description Commercial Banking
enrichData.organization.industryCodes[0].priority 1
enrichData.organization.industryCodes[0].typeDescription North American Industry Classification System 2017
enrichData.organization.industryCodes[0].typeDnBCode 30832

  • If a customer is only interested in importing NAICS industries, then the import procedure should only load industryCodes where typeDescription = "North American Industry Classification System 2017"
  • If a customer only wants the primary SIC industry, then the import procedure should only load industryCodes where typeDescription = "US Standard Industry Code 1987 - 4 digit" and priority = 1

All data element arrays are defined and explained in the Data Dictionary.

Sample Output Data

Download

Click here to download all the sample files that can be used as templates for creating new input files and view output files.