Data File Batch (EmailVerification) Guide

Overview

The Email Verification Batch API allows the user to submit a file of emails to be verified and enriched with data and insights to better gauge the validity, risk, and deliverability of your email data, so you can engage smarter and more efficiently. The Email Verification Batch mode allows users to submit a CSV file of emails and the processed file can optionally be CSV, JSON or zipped. Features are available to securely upload your file, check the status and download the processed file.

Process Overview and Security

DataFileBatch-Process Flow

To utilize the Data File Batch API, you will need to do the following:
NOTE: Use of the D&B APIs requires an access token. Refer to the Authentication page for more details on the steps involved in authenticating.

  1. Create a file containing the records to be processed. See Input File Structure.
  2. Generate Customer Key values for S3. See Customer Key.
  3. Use the D&B Data File Batch Submit API to obtain a job ID and secured URL to which to upload the file. See the DataFileBatch Submission API page.
  4. Upload the file. See Input File Upload. Important: The file must be uploaded within 24 hours of submitting the request.
  5. Use the D&B Data File Batch Status API to check job status. See the DataFileBatch Status API page.
  6. When status code is 60104 (Processed), download output file. Also a confirmation email notification will be sent to customer once file is available to download. See Output File Download. Important: The file must be downloaded within 24 hours of request completion.

Below is the operation available as part of data file batch delivery of D&B Data Blocks:

  1. EmailVerification

For a complete samples, see the Email Verification (Batch) Samples page.

Data File Batch Submission

The following configuration selections should be provided by the customer while submitting Data File Batch.

Element Name JSON Path Data Type Required Example Description
Process ID process string true EmailVerification A unique identifier assigned by Dun and Bradstreet to identify the business function to be performed on the input. Valid values:
  • EmailVerification
Input Specification File Name inputSpecification.fileName string true Profile1Input_Batch# The file name of the batch to be processed.
Input Specification Record Layout inputSpecification.recordLayout string true DPlus json The name of the defined format of the records. Valid values:
  • DPlus json
  • Flat-File
Input Specification Record Delimiter inputSpecification.recordDelimiter string true LF The delimiter used in the file to separate records. Valid values:
  • LF
  • CRLF
Input Specification Field Delimiter inputSpecification.fieldDelimiter string false | The delimiter used in the file to separate each field in a record.
Input Specification Enclose Character inputSpecification.encloseCharacter string false " A single character used to enclose the field when it contains field or record delimiter character. Default is double quotes (") when not specified.
Input Specification Escape Character inputSpecification.escapeCharacter string false \ A single character used to escape the enclose character in the field. Default is encloseCharacter when not specified.
Input Specification Enclosing mode inputSpecification.enclosingMode string false MINIMAL The mode used to mention how to enclose field or record. Valid values:
  • MINIMAL (default) - Enclose field only when field contains field or record delimiter character.
  • ALL - Enclose all fields always.
  • NONNUMERIC - Enclose all non numeric fields.
  • NONE - All fields are not enclosed.
Input Specification Has Header inputSpecification.hasHeader boolean false true When 'true' this denotes that the header record is included (default). When 'false' this denotes that the header record is not included.
Input Specification Encoding inputSpecification.encoding string false UTF-8 The character encoding scheme in which the file is prepared. Valid values:
  • UTF-8 (default)
  • UTF-16
  • UTF-16BE
  • UTF-16LE
Input Specification Character Set inputSpecification.compressionType string false Unicode The character set in which the file is prepared. Valid values:
  • Unicode
Input Specification Compression Type inputSpecification.compressionType string false gzip The compression technique used for the provided file. Valid values:
  • gzip
  • zip
Output Specification Record Layout outputSpecification.recordLayout string true DPlus json The name of the defined format of the records. Valid values:
  • DPlus json
  • Flat-File
Output Specification Record Delimiter outputSpecification.recordDelimiter string true LF The delimiter used in the file to separate records. Valid values:
  • LF
  • CRLF
Output Specification Field Delimiter outputSpecification.fieldDelimiter string false | The delimiter used in the file to separate each field in a record.
Output Specification Enclose Character outputSpecification.encloseCharacter string false " A single character used to enclose the field when it contains field or record delimiter character. Default is double quotes (") when not specified.
Output Specification Escape Character outputSpecification.escapeCharacter string false \ A single character used to escape the enclose character in the field. Default is encloseCharacter when not specified.
Output Specification Enclosing mode outputSpecification.enclosingMode string false MINIMAL The mode used to mention how to enclose field or record. Valid values:
  • MINIMAL (default) - Enclose field only when field contains field or record delimiter character.
  • ALL - Enclose all fields always.
  • NONNUMERIC - Enclose all non numeric fields.
  • NONE - All fields are not enclosed.
Output Specification Has Header outputSpecification.hasHeader boolean false true When 'true' this denotes that the header record is included (default). When 'false' this denotes that the header record is not included.
Output Specification Encoding outputSpecification.encoding string false UTF-8 The character encoding scheme in which the file is prepared. Valid values:
  • UTF-8 (default)
  • UTF-16
  • UTF-16BE
  • UTF-16LE
Output Specification Character Set outputSpecification.compressionType string false Unicode The character set in which the file is prepared. Valid values:
  • Unicode
Output Specification Compression Type outputSpecification.compressionType string false gzip The compression technique used for the provided file. Valid values:
  • gzip
  • zip
Notification Email Address notificationDetail.emailAddress string false test@test.com Email address provided by the Customer/User to which the notification should be delivered.
Email Verification Specification Is Detail Verification Required emailVerificationSpecification.isDetailVerificationRequired boolean false true Provides a more detailed analysis to determine the deliverability of an email and this can require additional processing and testing. This approach attempts to reduce the number of ambiguous responses while providing a more accurate email deliverability rating and score. When parameter is not present or null, API will perform more detailed analysis.
Customer Key customerKey string true customer key A unique key (must have 32 characters) assigned by the customer while requesting for a batch submission, which will be used to calculate the signature of the S3 pre-signed-url. The customer should retain this key to access the S3 folder to upload the input file. Please note key must be base64 encoded.
Customer Reference customerReference string false internal unique identifier A free form reference string provided by the customer to be linked to the product in order to support subsequent order reconciliation.

Input File Specifications

Category Email Verification
File type Supported file types:
  • delimited text file (.txt)
  • comma-separate-value file (.csv)
  • json file (.json)
File Format Supported file formats:
  • Flat File
  • JSON
Row delimiter Supported row delimiters:
  • carriage return line feed (CRLF)
  • line feed (LF)
Enclosing Mode Supported enclosing mode:
  • MINIMAL (default) - Enclose field only when field contains field or record delimiter character.
  • ALL - Enclose all fields always.
  • NONNUMERIC - Enclose all non numeric fields.
  • NONE - All fields are not enclosed.
Encoding Supported encoding:
  • UTF-8 (default)
  • UTF-16
  • UTF-16BE
  • UTF-16LE
Character Set Supported character set:
  • Unicode
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
Header row A header row is required when hasHeader is set to "true" and header names must exactly match the specified names.
Column order The order of columns does not matter.
File compression Supported compression types:
  • gzip
  • zip
File naming Name can contain whole numbers, latin letters, "_", "-", and ".". Any other characters (such as "/", non-latin letters, "&", "%") are not permitted.


For a complete samples, see the DataFileBatch Samples page.

Email Verification Input File

The following input fields are supported:

Element Name Column Header for Input File Data Type Required Example Description
Email Address emailAddress string true jones@dnb.com An email address used to identify an entity by its email domain.
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

For detailed explanations of the parameters, see the Query Parameters section on the Email Verification API page.

Flat-File recordLayout with only emailAddress
emailAddress
test@test.com
test1@test.com
Flat-File recordLayout with emailAddress and one customerReference[0]
emailAddress,customerReference[0]
test@test.com,reftext
test1@test.com,reftext1
Flat-File recordLayout with emailAddress and all customerReference
emailAddress,customerReference[0],customerReference[1],customerReference[2],,customerReference[3],customerReference[4]
test@test.com,reftext,ref1text,ref2text,ref3text,ref4text
test1@test.com,reftext1
DPlus json recordLayout
{"emailAddress":"test@test.com"}
{"emailAddress":"test1@test.com", "customerReference": ["reftext"]}
{"emailAddress":"test2@test.com", "customerReference": ["reftext,reftext1"]}

Email Verification Output File

The following are the list of all output fields supported:

Element Name Column Header for Output File Data Type Required Example Description
Sequence Number sequenceNumber integer true 1 A number assigned by the Dun & Bradstreet batch system to this input record from the customer file to internally manage the tracking and ordering of the records between the input and output files.
Customer Reference Text customerReference array (string) false CustomerRecordID#1, My high profile companies A collection of free form references provided by the customer to be linked to the process, in order to support subsequent order reconciliation. This could be used by the customers to pass any unique record identifiers for their pruposes. Dun & Bradstreet systems simply retrun the values along with the records and is not used for any processing. Note: Customer Billing Endorsement is not expected to be provided here
Is Duplicate Record isDuplicateRecord boolean false false When set to "true" indicates that this record appears more than once in the batch.When set to "false" indicates that this record appears only once in the batch.
Result Process result.process string true EmailVerification A unique identifier assigned by Dun and Bradstreet to identify the business function to be performed on the input.
Result Code result.code string true 00000 A number assigned by D&B which uniquely identifies the reason for failure of this request.
Result Message result.description string true Success An explanatory text providing more details about the reason for failure of this request.
Result Parameter Name result.resultDetails.parameter string false The request parameter on which the error was identified.
Result Details Code result.resultDetails.code string false Records the actual error identified on the request parameter.
Result Details Description result.resultDetails.description string false Request missing required element An explanatory text providing more details about the reason for failure of this request parameter.
Inquiry Detail EmailAddress inquiryDetail.emailAddress string false test@test.com The Email Address provided in the request.
For response parameters, see the Email Verification API page for more details.

Sample Output Data

For detailed explanations of the parameters, see the RESPONSES section on the Email Verification API page.

Flat-File output
sequenceNumber,customerReference[0],customerReference[1],customerReference[2],customerReference[3],customerReference[4],isDuplicateRecord,result.process,result.code,result.description,result.resultDetails.0.parameter,result.resultDetails.0.code,result.resultDetails.0.description,inquiryDetail.emailAddress,emailVerificationDetails.threatRisk,emailVerificationDetails.disposition,emailVerificationDetails.deliverabilityScore,emailVerificationDetails.deliverabilityRating,emailVerificationDetails.emailType,emailVerificationDetails.isRoleEmail,emailVerificationDetails.isFreeEmail,emailVerificationDetails.serviceType,emailVerificationDetails.emailServerCountryISOAlpha2Code,emailVerificationDetails.isDisposable,emailVerificationDetails.isDarkWeb
1,,,,,,false,EmailVerification,00000,Success,,,,test@test.com,Y,,,Email Threat Risk,,,,,,,
2,,,,,,false,EmailVerification,00000,Success,,,,test1@test.com,Y,,,Email Threat Risk,,,,,,,
3,,,,,,false,EmailVerification,00000,Success,,,,test@testing.com,Y,,,Email Threat Risk,,,,,,,
4,,,,,,false,EmailVerification,00000,Success,,,,test@demo.com,N,Failed Delivery,7,Very Poor,Business,false,false,Other,US,false,false
5,,,,,,false,EmailVerification,00000,Success,,,,test2@test.com,N,Failed Delivery,7,Very Poor,Business,false,false,Other,US,false,false
Dplus json output
{"result": {"description": "Success", "process": "EmailVerification", "code": "00000"}, "sequenceNumber": 1, "isDuplicateRecord": false, "inquiryDetail": {"emailAddress": "test@test.com"}, "emailVerificationDetails": {"deliverabilityRating": "Email Threat Risk", "threatRisk": "Y"}}
{"result": {"description": "Success", "process": "EmailVerification", "code": "00000"}, "sequenceNumber": 2, "isDuplicateRecord": false, "inquiryDetail": {"emailAddress": "test1@test.com"}, "emailVerificationDetails": {"deliverabilityRating": "Email Threat Risk", "threatRisk": "Y"}}
{"result": {"description": "Success", "process": "EmailVerification", "code": "00000"}, "sequenceNumber": 3, "isDuplicateRecord": false, "inquiryDetail": {"emailAddress": "test@testing.com"}, "emailVerificationDetails": {"deliverabilityRating": "Email Threat Risk", "threatRisk": "Y"}}
{"result": {"description": "Success", "process": "EmailVerification", "code": "00000"}, "sequenceNumber": 4, "isDuplicateRecord": false, "inquiryDetail": {"emailAddress": "test@demo.com"}, "emailVerificationDetails": {"serviceType": "Other", "disposition": "Failed Delivery", "isFreeEmail": false, "isDisposable": false, "deliverabilityScore": 7, "emailType": "Business", "emailServerCountryISOAlpha2Code": "US", "threatRisk": "N", "isDarkWeb": false, "deliverabilityRating": "Very Poor", "isRoleEmail": false}}
{"result": {"description": "Success", "process": "EmailVerification", "code": "00000"}, "sequenceNumber": 5, "isDuplicateRecord": false, "inquiryDetail": {"emailAddress": "test2@test.com"}, "emailVerificationDetails": {"serviceType": "Other", "disposition": "Failed Delivery", "isFreeEmail": false, "isDisposable": false, "deliverabilityScore": 7, "emailType": "Business", "emailServerCountryISOAlpha2Code": "US", "threatRisk": "N", "isDarkWeb": false, "deliverabilityRating": "Very Poor", "isRoleEmail": false}}

Customer Key

The Data File Batch API makes use of Amazon S3 as a temporary storage for the input and output files. For security purposes, a "customer key" is used to encrypt the contents.

For more information about Amazon Server-Side Encryption and Customer-Provided Encryption Keys visit Amazon's documentation site: http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html#RESTObjectPUT-requests

To create a customer key (must have 32 characters), you can use the below provided generator or follow the steps below:

  1. BASE64 encode your D&B Direct+ Consumer Key. NOTE: If Consumer Key has more than 32 characters, use first 32 characters for encoding.
  2. Copy the result and save it for use in the API as x-amz-server-side-encryption-customer-key and in the Header as Customer Key value.
  3. MD5 encode your D&B Direct+ Consumer Key. NOTE: If Consumer Key has more than 32 characters, use first 32 characters for encoding.
  4. Copy the result.
  5. Decode this hex result into BASE64.
  6. Copy the result for use in the API as x-amz-server-side-encryption-customer-key-MD5.

Customer Key and Customer Key MD5 generator

Paste your D&B Direct+ Consumer Key (must have 32 characters) provided to you when you registered for access to the Direct+ API into the text box field and click on 'Generate' button.
NOTE: If Consumer Key has more than 32 characters, use first 32 characters for encoding.

Please paste your Consumer Key

Input File Upload Request

Use this request to upload a file for a Data File Batch-Process job already submitted.

Request Header

Name Characteristics
x-amz-server-side-encryption-customer-key Required

Customer Key generated by base64-encoding your D&B Direct+ Consumer Key.
x-amz-server-side-encryption-customer-algorithm Required

Algorithm name which is always "AES256".
x-amz-server-side-encryption-customer-key-MD5 Required

Customer key generated from Base64 encoding of your D&B Direct+ Consumer Key MD5 value.

URL

For the request, copy the batchSubmissionDetail.contentURL from the DataFileBatch POST response.

Sample Request (Input File Upload PUT)
PUT https//prd-batch-request.s3.amazonaws.com/batch-request-uploads/1000305/request/XXXXXXXXXX/file.csv?X-Amz-Security-Token=...&X-Amz-Algorithm=xxxxxxx&X-Amz-Date=20160901T093114Z&X-Amz-SignedHeaders=host%3Bx-amz-server-side-encryption-customer-algorithm%3Bx-amz-server-side-encryption-customer-key%3Bx-amz-server-side-encryption-customer-key-md5&X-Amz-Expires=86399&X-Amz-Credential=...&X-Amz-Signature=...

Output File Download Request

Use this feature to download the file when processing is complete.

Request Header

Name Characteristics
x-amz-server-side-encryption-customer-key Required

Must use same key as used on the initial job submission request.

Field value <Customer key generated by SDK>
x-amz-server-side-encryption-customer-algorithm Required

Must use algorithm name.

Field value "AES256"
x-amz-server-side-encryption-customer-key-MD5 Required

Can be generated either using SDK, Java standard library or any MD5 hashing web service.

Field value <Customer key MD5 hash>

URL

For the request, copy the batchDetail.outputDetail.contentURL from the DataFileBatch GET Status response.

Sample Request (Output File Download)
GET https//prd-batch-request.s3.amazonaws.com/batch-request-uploads/1000305/request/xxxxxxx/file.csv?X-Amz-Security-Token=...&X-Amz-Algorithm=xxxxx&X-Amz-Date=20160901T093114Z&X-Amz-SignedHeaders=host%3Bx-amz-server-side-encryption-customer-algorithm%3Bx-amz-server-side-encryption-customer-key%3Bx-amz-server-side-encryption-customer-key-md5&X-Amz-Expires=86399&X-Amz-Credential=...&X-Amz-Signature=...

DNB Full Logo Direct+ Product Documentation