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:
End-to-end process of D&B Data Blocks Data File Delivery

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

Entity Resolution
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:

Flat File - CSV Flat File - Pipe delimited JSON

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

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):

Download the Excel file
Enable the Macros at the top of the Excel file, if it is not enabled
Click on the button "Filter Data Blocks & Packets" and select the Data Block and Level you are interested in
Results will be shown once the progress is 100% complete
Column D "JSON PATH" contains the field headers in the output files
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
Click on the button "Show All" to clear the Macros filter and show all the "JSON PATH"

Option 2 (Manual Filtering):

Download the Excel file
Scroll right to find the Data Block and Level you are interested in
Filter on "Y"
Column D "JSON PATH" contains the field headers in the output files

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:

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

The data element "industryCodes" may have >20 values for a company. These values will be placed in columns industryCodes[0], industryCodes[1], industryCodes[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

Flat File - CSV Flat File - Pipe delimited JSON

Download

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