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 Column Delimiter The delimiter in the customer input file. Options include:
  • pipe (|)
  • comma (,)
Trade Up Applies to Entity Resolution. 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 Column Delimiter The delimiter in the output file(s). 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
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 false 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.
Business Registration Number Type organization.registrationTypeDnBCode integer false 1340 A unique code assigned by Dun & Bradstreet to identify the type of registration number.
List of supported codes
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
Click here to download sample files that can be used as templates for creating new input files:

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:

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

Data Block output files contain three sections of data:

Section How to identify
Client Input fields Data elements beginning with "inquiryDetail."
Company Entity Resolution data elements Data elements beginning with "matchData." and "result[0]."
Enriched Data Block elements Data elements beginning with "enrichData."

Sample Output Data

Choose the details from table below to download respective sample file:

Operation Type Column Delimiter Data Block Sample File
Entity Resolution
Company Entity Resolution
Enrich Only

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