Multi-Process Guide

The Direct+ Multi-Process API allows customers to request batch processing of records. The following processes are supported:

• Match (match)
  For each input record, identifies the single most likely match for the given criteria. The response content for each record, if a match is found, is the same as for Identity Resolution API. This feature is design to handle up to 25,000 records per request.

• Match & Append (extmatch)
  For each input record, identifies the single most likely match for the given criteria and then appends a data product to the response. This feature is design to handle up to 25,000 records per request.

• Batch Match (hvmatch)
  For each input record, identifies the single most likely match. The response content for each record, if a match is found, is the same as for Identity Resolution API. This feature is designed to handle up to 1 million records per request.
  IMPORTANT: Batch Match requires additional capacity; please contact your Dun & Bradstreet representative for more information.

Process Overview and Security

To utilize the Multi-Process 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 Multi-Process Submit API to obtain a job ID and secured URL to which to upload the file. See the Job 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 Multi-Process Status API to check job status. See the Job Status API page.
6. When status code is 60104 (Processed), download output file. See Output File Download. Important: The file must be downloaded within 24 hours of request completion.

Input File Structure

The file:

• Name can contain whole numbers, latin letters, "_", "-", and ".". Any other characters (such as "/", non-latin letters, "&", "%") are not permitted.
• Format must be .csv.
• Maximum file size:
  • For Match and Match & Append: 10 MB.
  • For Batch Match: 1 GB

File contents:

• All input files must be URL encoded.
• Each record in the file must be on a separate line and contain: {recordID},{parameters}

Name	Characteristics
recordID	Element, string, maximum 16 chars A unique identifier assigned by calling application to identify a specific request provided in the input file.
parameters	Element, string The request parameters acceptable by the specific process invoked by the customer application. This should be in the same format as accepted by the Identity Resolution API URL. For permissible parameters, see the Query Parameters section on the Identity Resolution API page.

For a complete sample file, see the Multi-Process Sample Files page.

Sample Record

For detailed explanations of the parameters, see the Query Parameters section on the Identity Resolution API page.

Match

RQ001, name=AVNET%20EUROPE%20COMM%20VA&streetAddressLine1=KOUTERVELDSTRAAT%2020&streetAddressLine2=&countryISOAlpha2Code=BE&addressLocality=MACHELEN&addressRegion=&postalCode=1831&inLanguage=en-US&confidenceLowerLevelThresholdValue=8&candidateMaximumQuantity=1

Extended Match

RQ001, name=AVNET%20EUROPE%20COMM%20VA&streetAddressLine1=KOUTERVELDSTRAAT%2020&streetAddressLine2=&countryISOAlpha2Code=BE&addressLocality=MACHELEN&addressRegion=&postalCode=1831&inLanguage=en-US&confidenceLowerLevelThresholdValue=8&candidateMaximumQuantity=1

High-Volume Match

RQ001, name=AVNET%20EUROPE%20COMM%20VA&streetAddressLine1=KOUTERVELDSTRAAT%2020&streetAddressLine2=&countryISOAlpha2Code=BE&addressLocality=MACHELEN&addressRegion=&postalCode=1831&inLanguage=en-US

Customer Key

The Multi-Process 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, you can use the provided SDK 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.

Please see the Appendix for a walk through of this process on a third-party online converter site.

Input File Upload Request

Use this request to upload a file for a Multi-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 jobSubmissionDetail.url from the Job Submission response.

Sample Request (Input File Upload PUT)

PUT https//prd-multi-request.s3.amazonaws.com/multi-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 outputDetail.contentURL from the Job Status response.

Sample Request (Output File Download)

GET https//prd-multi-request.s3.amazonaws.com/multi-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=...

Output File Format

Name	Characteristics
recordID	Element, string, maximum 16 chars A unique identifier assigned by calling application to identify a specific request provided in the input file.
{comma}
HTTPStatus	Element, string The HTTP Status returned by the requested service for this request.
{comma}
processResponse	Element, string The response generated by the processing application for this request. For response parameters, see the Identity Resolution API page.
{end of line}

Appendix

The information below is an example of how you could generate Customer Keys. The screen shots are from a third-party site (https://conv.darkbyte.ru/). Dun & Bradstreet has no association with this site and you may use any method of encoding you prefer; the screen shots are for purposes of this documentation only.

1. Paste the your D&B Direct+ Consumer Key provided to you when you registered for access to the Direct+ API into the Text field. NOTE: If Consumer Key has more than 32 characters, use first 32 characters for encoding.
2. Select Encode.
3. Copy the value from the BASE64 field and save it; this will be used in API calls as the x-amz-server-side-encryption-customer-key value and in the Header as Customer Key value.

4. Copy the returned MD5 value.

   

5. Past the MD5 value into the Hex field.

6. Select Decode.

   

7. Copy the value from the BASE64 field and save it; this will be used in the API as the x-amz-server-side-encryption-customer-key-MD5 value.