Cookies Settings

Loading

dnb-logo
Direct 2.0
Collapse

On-Demand Multiple Entity Resolution (Asynchronous)

Also referred to as Medium (up to 10,000 companies) Batch Cleanse Initiation.

This feature allows multiple cleanse and match requests to be issued from a single API call, using the Batch Service to support medium-sized batches (fewer than 10,000 companies). The process involves creating two request files: one containing the companies (and available details) that should be cleansed and matched, and the match specification parameters.

NOTE: Effective Sept 1, 2015, the On Demand Multiple Entity Resolution product will be available on a limited basis. Existing contract commitments will continue to be fully supported. Please contact a D&B sales representative for additional details.

Update History

  • June 20, 2014 (v3.0 SOAP & REST): The REST implementation now supports transfer/receipt of embedded base64 encoded ContentObjects. The SOAP implementation now supports transfer/receipt using the MTOM protocol (multi-part attachments).
  • May 16, 2014 (v2.0 SOAP & REST): Error codes refined to improve usability/implementation.
  • October 3, 2013 (v1.0 SOAP & REST): The current implementation of this service accepts embedded base64 Content Objects for SOAP, and multipart attachments (MTOM) for REST. Both implementations support XML only.

Quick Start for Medium Batches

The process for medium batches requires the following steps:

  1. List Preparation - there is a specific layout/format, naming and size limit of the files that you will submit for cleanse/match processing.
  2. List Uploads - when you're ready to initiate a batch, submit the list (i.e. ProcessBatch) and control file for processing.
  3. Get Ready for the Results - like the initial list, the results will be in a specific layout/format.
  4. Downloading Results - use the list batch operation to poll for a completed status and then download the results (i.e., GetBatchResults).

Feature Request

IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.

Overview

The product request details is submitted as a list of comma-delimited entries.

This operation also requires that a second text file be prepared and attached to the request. The second file must have a file extension of "XML" and include the following match specification parameters in XML format.

Sample Specification
<com:GetCleanseMatchRequest xmlns:com="http://services.dnb.com/CompanyServiceV2.0" ServiceVersionNumber="1">
         <GetCleanseMatchRequestDetail>
            <InquiryDetail>               
            </InquiryDetail>
            <MatchSpecification>
               <ConfidenceLowerLevelThresholdValue>7</ConfidenceLowerLevelThresholdValue>
               <ExclusionCriteria>
                  <ExclusionDataDescription>Exclude Undeliverable</ExclusionDataDescription>
               </ExclusionCriteria>
               <IncludeCleansedAndStandardizedInformationIndicator>true</IncludeCleansedAndStandardizedInformationIndicator>
            </MatchSpecification>        
         </GetCleanseMatchRequestDetail>
</com:GetCleanseMatchRequest>
XML ElementDescription
GetCleanseMatchRequest. GetCleanseMatchRequestDetail. MatchSpecification. ConfidenceLowerLevelThresholdValue

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.

Possible Values: 1 – 10

GetCleanseMatchRequest. GetCleanseMatchRequestDetail. MatchSpecification. ExclusionCriteria. ExclusionDataDescription

Can repeat multiple times to allow the recording of filtering requirements that a service should apply to prevent subjects from being returned in a match response. For example exclude subjects from the candidate list that are out of business.

Possible Values: Exclude Non Marketable, Exclude Out of Business, Exclude Undeliverable.

GetCleanseMatchRequest. GetCleanseMatchRequestDetail. MatchSpecification. IncludeCleansedAndStandardizedInformationIndicator

When TRUE this denotes that the cleansed and standardized information should be included in the response.

When FALSE this denotes that the cleansed and standardized information should not be included in the response.

Possible Values: true / false

NOTE: Please refer to the On-Demand Single Entity Resolution documentation for minimum requirements for and search behavior of matching.

Data Layer Entitlement

For customers in U.S. and Canadian markets, the API is provisioned for specific collections of products, reports, and/or features (collectively referred to as data layers) for production and trial usage. Entitlement is not required for testing in the sandbox environment.

  • This report is entitled as "On-Demand Multiple Entity Resolution" for D&B Direct 2.0 customers, and also requires that "On-Demand Single Entity Resolution" be entitled.

For customers in the UK, Ireland, Belgium, Netherlands and Luxembourg markets, the API is provisioned as a specific set of data layers for production, trial, and sandbox usage.

  • This particular data layer is NOT included in the D&B Direct Onboard suite.

Specification

Exception: The expiration of Authentication Tokens for this service is 30 minutes.

Exception: This operation currently does not support JSON. Requests must be submitted in XML format.

The number of product requests allowed per operation batch is designated on the customer contract (up to a maximum of 10,000).

Calls to this operation must be submitted as a multi-part (MIME) POST request, with the batch request file(s) appended as separate parts. As per the standard, the “Content Type” in the main header should be:

Content-Type: Multipart/form-data
Content-Transfer-Encoding: 8bit

Alternatively, the batch request files(s) may be embedded as base64 encoded Content Objects. As per the standard, the “Content Type” in the main header should be:

Content-Type: Application/XML

It is recommended that the user follow Multipart/base64Binary standards for passing the content type in the header.

The following parameters are accepted by this operation; however, this operation can only be invoked using a POST request.

Restriction: The sequence of Request Parameters submitted to POST/PUT operations currently MUST follow the order presented in this section. This applies to REST calls only.

Sample Request (Embedded)
POST https://direct.dnb.com/V1.0/Batches HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: multipart/form-data; boundary="----=_Part_14_31793330.1514469595477"
MIME-Version: 1.0
Authorization: HoObE/2StpE62O/TDyQBpoFwmvDjiRN7neH6Qp5eEDBqkl6kzZdBwDXaihfxIqH+5g26crK2RUD9SXdDMZ+hbuRKfxCJuuIAYVmVBZBhv4pMjXwvznG687fn7bP3bdTsPy09fjMMnrt5YTZ/RApbcCm8mrg1NYwPFv8QNtDHWKMNXtk0835QZc/msuWN5JUA3Kjfo9Q0st+811sf/NWIaBJSjkZmtLBCgU1uh55kigjfBQvtSABzcwy5Oar7w02/NPJA/QjfOalyrQLDF2NZO3EJ4qu447Ro7wsoElr+dROAfPlE/l2W2wNckIoNYb5GgGDR/WyQ2geVyPp6+ewvWg==
ApplicationID: 37
Content-Length: 3352
Host: direct.dnb.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)


------=_Part_14_31793330.1514469595477
Content-Type: multipart/form-data
Content-Transfer-Encoding: 8bit

JUne21&_Prod_01011582013-05-21T09:30:47.0ZCPCM_CM10XMLCompany ServiceCSVPCMGBIMatch1.02342336None50CSVZIPMatch_DB=AOS
------=_Part_14_31793330.1514469595477
Content-Type: text/xml; charset=Cp1252; name=GetCleanseMatchRequest.xml
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="GetCleanseMatchRequest.xml"; filename="GetCleanseMatchRequest.xml"

8Exclude Non MarketableExclude Out of Businessfalse
------=_Part_14_31793330.1514469595477
Content-Type: application/octet-stream; name=Sample.csv
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="Sample.csv"; filename="Sample.csv"

,1,,,,,,,804735132,"GORMAN MANUFACTURING COMPANY, INC.",,492 KOLLER ST,,SAN FRANCISCO,,94110,,US,,06505550000,,
,2,,,,,,,214567885,"D & B SAMPLE CO LTD",,MARLOW INTERNATIONAL PARKWAY,,MARLOW,,SL7 1AJ,,GB,,98841212120,,
,3,,,bloomberg.net,,,,,,,,,,,,,,,,,
,4,,,,test@bloomberg.net,,,,,,,,,,,,,,,,
,5,,,,,,,,bloomberg.net,,,,,,,,US,,,,

------=_Part_14_31793330.1514469595477--


Sample Request (MTOM)
Name Characteristics
ProcessBatchRequest Aggregate
ProcessBatchRequest. BatchDetail Aggregate, Required

Records information necessary to process a particular request.

ProcessBatchRequest. BatchDetail. ApplicationBatchID string up to 64 chars., Required

A number assigned by consuming application (e.g., GIH) which is used to uniquely identify a batch request.

ProcessBatchRequest. BatchDetail. MessageTimeStamp dateTime, Required

The date and time when this message was created. When the message is from an intermediary, such as a workflow manager or service bus, this is the date and time when the message was sent to or from the D&B function,

END: ProcessBatchRequest. BatchDetail /Aggregate
ProcessBatchRequest. BatchSpecification Aggregate, Required

Records specific information that are required for processing a Batch Request.

ProcessBatchRequest. BatchSpecification. BatchProcessID string up to 32 chars., Required

A number assigned by the composite service which is used to uniquely identify the business function to be performed (e.g., Match, Cleanse, Match and Cleanse).

Possible values: CPCM_CM

ProcessBatchRequest. BatchSpecification. BatchSpecificationObject Aggregate, Optional (Array)

Possible values: Should give one specification Object for CPCM_CM

ProcessBatchRequest. BatchSpecification. BatchSpecificationObject. ContentObject For Multipart: Include statement1, Required

Example: <Include href="cid:Control.xml"/>

For Embedded: base64Binary, Required

ProcessBatchRequest. BatchSpecification. BatchSpecificationObject. ObjectFormatTypeText string up to 5 chars., Required

XML,CSV,JSON

Possible values: XML

ProcessBatchRequest. BatchSpecification. BatchSpecificationObject. LayoutName string up to 32 chars., Required

The name of the layout for this collection of the data records. For example the layout names 'GBI' denotes the Global Batch Input layout.

Possible values: Company Service

END: ProcessBatchRequest. BatchSpecification. BatchSpecificationObject /Aggregate
END: ProcessBatchRequest. BatchSpecification /Aggregate
ProcessBatchRequest. InputDetail Aggregate, Required

Records information about the input into the Batch process.

ProcessBatchRequest. InputDetail. InputObjectDetail Aggregate, Optional (Array)
ProcessBatchRequest. InputDetail. InputObjectDetail. ContentObject For Multipart: Include statement2, Required

Example: <Include href="cid:Request.csv"/>

For Embedded: base64Binary, Required

ProcessBatchRequest. InputDetail. InputObjectDetail. ObjectFormatTypeText string up to 5 chars., Required

XML,CSV,JSON

Possible values: CSV

ProcessBatchRequest. InputDetail. InputObjectDetail. LayoutName string up to 32 chars., Required

The name of the layout for this collection of the data records. For example the layout names 'GBI' denotes the Global Batch Input layout.

Possible values: PCMGBIMatch

ProcessBatchRequest. InputDetail. InputObjectDetail. LayoutVersion string up to 10 chars., Required

The version of the Layout

Possible values: 1.0

ProcessBatchRequest. InputDetail. InputObjectDetail. CompressTypeValue string up to 64 chars., Optional

Text that describes the compresssion software that has been used to reduce the size of this collection of data records.

Possible values: None

ProcessBatchRequest. InputDetail. InputObjectDetail. RecordsCount unsignedLong, Optional

A numeric value denoting the number of records contained in the input file.

Possible values: vary based on performance and customer

END: ProcessBatchRequest. InputDetail. InputObjectDetail /Aggregate
END: ProcessBatchRequest. InputDetail /Aggregate
ProcessBatchRequest. OutputSpecification Aggregate, Required

Records information about the output specification.

ProcessBatchRequest. OutputSpecification. ObjectFormatTypeText string up to 5 chars., Required

XML,CSV,JSON

Possible values: CSV

ProcessBatchRequest. OutputSpecification. CompressTypeValue string up to 64 chars., Optional

Text that describes the compresssion software that has been used to reduce the size of this collection of data records.

Possible values: None

END: ProcessBatchRequest. OutputSpecification /Aggregate
END: ProcessBatchRequest /Aggregate

1 The file contents should be appended to the request as a separate part. The file name specified in the Include statement must match the part header:

Content-Type: text/xml; charset=Cp1252; name=Control.xml
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="Control.xml"; filename="Control.xml"

2 The file contents should be appended to the request as a separate part. The file name specified in the Include statement must match the part header:

Content-Type: application/octet-stream; name=Request.csv
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="Request.csv"; filename="Request.csv"

Endpoint

Use the following endpoint for requesting this feature. The {version} is dependent on the underlying service delivering the response.

Endpoint (Batch)
POST https://direct.dnb.com:8443/V{version}/Batches

NOTE: Calls to the Batch service use an alternate port (8443).

Testing

This operation will return a static set of results in the D&B Direct test environment (sandbox), regardless of the request parameters.

NOTE: All sandbox requests for this service require the following fixed authentication token:
jAu4dMpeUcgrDE0J66k3x5AUm+3ej7Dq2+Pl2TTwtbOC06c+szLpjs8yzMYFKvjPXOBrGRCr61LkVedVC9w0NChRFMUlWopw/KQRv9GHWDOV5yvK43Tt4fTYA6cgVef9wb572rHNHlisRFm4789nw8re+K9jgoO9LvlIhs9IgZUbGRaIAttKDYFmtLSKDmjjZWoo7RPiwqaZR4dFLQ86v10038clavB/lqJtu6zo6qmep7Na2xU7Ot+UcWA0bMA18gnFikzptbbqu/DP6Fa89s6itBrEbFn5iD88KCRPQfImtD6li7g+Rt7CdracVkQv7vkxO9LvrVc4YqTVJX51xqzuP1HuCYE3/Kdnn1B3pSZjw4xy5nq03LFu8HJ9VF89

Feature Response

Specification

Exception: This operation currently does not support JSON. The following is a list of the possible data fields returned by this operation in the XML response.

NOTE: The D-U-N-S Number returned in the response will be a nine-digit zero-padded, numeric value.

Sample Response (Embedded)
<ns1:ProcessBatchResponse ServiceVersionNumber="3.0" xmlns:oracle-xsl-mapper="http://www.oracle.com/xsl/mapper/schemas" xmlns:ns1="http://services.dnb.com/BatchServiceV1.0" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing">
   <BatchDetail>
      <ApplicationBatchID>JUne21&amp;_Prod_0101158</ApplicationBatchID>
      <ServiceBatchID>125873E1</ServiceBatchID>
   </BatchDetail>
   <BatchResult>
      <SeverityText>Information</SeverityText>
      <ResultID>CM000</ResultID>
      <ResultText>Success</ResultText>
      <ResultMessage>
         <ResultDescription>Request Message has been placed in the Queue Successfully</ResultDescription>
      </ResultMessage>
   </BatchResult>
   <BatchProcessSummary>
      <ExecutionTimeSummary>
         <BatchRequestCreatedTimeStamp>2013-05-21T09:30:47.0Z</BatchRequestCreatedTimeStamp>
         <BatchReceivedTimeStamp>2017-12-28T08:59:57.139-05:00</BatchReceivedTimeStamp>
      </ExecutionTimeSummary>
      <RecordSummary>
         <TotalInputRecordCount>50</TotalInputRecordCount>
      </RecordSummary>
      <BatchPriorityValue>5</BatchPriorityValue>
   </BatchProcessSummary>
</ns1:ProcessBatchResponse>

Sample Response (MTOM)
Name Characteristics
ProcessBatchResponse Aggregate
ProcessBatchResponse@ServiceVersionNumber Attribute
ProcessBatchResponse. BatchDetail Aggregate
ProcessBatchResponse. BatchDetail. ApplicationBatchID Element
ProcessBatchResponse. BatchDetail. ServiceBatchID Element
END: ProcessBatchResponse. BatchDetail /Aggregate
ProcessBatchResponse. BatchResult Aggregate
ProcessBatchResponse. BatchResult. SeverityText Element

Possible values: Error; Fatal; Information; Warning

ProcessBatchResponse. BatchResult. ResultID Element

Possible values: BC005; CM001; CM004; BC001; BC002; BC003; BC004; CM003

ProcessBatchResponse. BatchResult. ResultText Element

Possible values: CM000 Success; BC005 Intermediate Notification; CM001 The given request is invalid; CM004 Internal D&B system error. Please try again or contact your local Customer Service Center; BC001 Partial Success; BC002 Batch request is not processed since input file is not available in the specified location; BC003 Batch request is not processed since the content of the input file is not in the expected format or has invalid data; BC004 Batch request is not processed since the count of the records specified in the request do not match the exact count of records in the input file;

ProcessBatchResponse. BatchResult. ResultMessage Aggregate
ProcessBatchResponse. BatchResult. ResultMessage. ResultDescription Element
END: ProcessBatchResponse. BatchResult. ResultMessage /Aggregate
END: ProcessBatchResponse. BatchResult /Aggregate
ProcessBatchResponse. BatchProcessSummary Aggregate
ProcessBatchResponse. BatchProcessSummary. ExecutionTimeSummary Aggregate
ProcessBatchResponse. BatchProcessSummary. ExecutionTimeSummary. BatchRequestCreatedTimeStamp Element
ProcessBatchResponse. BatchProcessSummary. ExecutionTimeSummary. BatchReceivedTimeStamp Element
END: ProcessBatchResponse. BatchProcessSummary. ExecutionTimeSummary /Aggregate
ProcessBatchResponse. BatchProcessSummary. RecordSummary Aggregate
ProcessBatchResponse. BatchProcessSummary. RecordSummary. TotalInputRecordCount Element
END: ProcessBatchResponse. BatchProcessSummary. RecordSummary /Aggregate
ProcessBatchResponse. BatchProcessSummary. BatchPriorityValue Element

Possible values: 1 to 10; 10 - High; 1 - Low

END: ProcessBatchResponse. BatchProcessSummary /Aggregate
END: ProcessBatchResponse /Aggregate

Response Codes & Error Handling

Successful service requests will return a CM000 response code in the BatchResult ResultID field. Otherwise, one of the D&B Direct standard response codes will be returned.

This operation may return the following response codes: BC009, CM001, CM002, CM003, CM004, and SC001-SC006.

NOTE: For this operation, the CM000 success response code indicates the batch was accepted for processing, NOT that the batch completed. To obtain the status for a batch, use the GetBatchResults operation.

D&B Direct 2.0 API requests are provided on a metered basis; and may require entitlement prior to use in the production environment. In addition, a concurrency limit (QPS) is monitored to ensure that it is not exceeded. An error code will be returned in the event that a transaction is throttled.

Qualified usage (e.g., a successful response) is tracked and billed according to the terms & conditions of the customer's contract. The response codes CM000, CM010, PD002 and PD015 are considered successful. A built-in feature exists to prevent duplicate billing when multiple successful requests with the same criteria are submitted on the same calendar day (which is based on Eastern Standard Time [GMT-5]).

The usage details for a Medium batch request are summarized by country, and then recorded. Therefore, customer online usage (OLUS) reports will display multiple entries for each batch submitted.

Operation-specific supplemental response code explanations:

Return CodeError ScenarioResult TextResult Message
BC009User exceeded Max records/request limitBatch not processed as the input file contains more records than the permitted limit.Batch not processed as the input file contains more records than the permitted limit.
BC011When BatchProcessID under the aggregate BatchSpecification is wrongInvalid Batch Process Id provided in the request.BatchProcessID of BatchSpecification contains Invalid Value in the request
CM000SuccessSuccessRequest Message has been placed in the Queue Successfully
CM001Multiple "BatchSpecificationObject" present in the requestThe given request is invalid.More than one BatchSpecificationObject attachments provided in the request.
CM001Multiple "InputObjectDetail" present in the requestThe given request is invalid.More than one InputObject attachments provided in the request.
CM001ApplicationBatchID is not presentThe given request is invalid.ApplicationBatchID is not present
CM001When LayoutName under the aggregate InputObjectDetail is incorrectThe given request is invalid.Input LayoutName should have value of "PCMGBIMatch".
CM001When ObjectFormatTypeText under the aggregate BatchSpecificationObject is wrongThe given request is invalid.ObjectFormatTypeText of BatchSpecificationObject contains invalid value in the request.
CM001When ObjectFormatTypeText under the aggregate InputObjectDetail is wrongThe given request is invalid.ObjectFormatTypeText of InputObjectDetails contains invalid value in the request.
CM001When BatchProcessID under the aggregate BatchSpecification is wrongThe given request is invalid.BatchProcessID of BatchSpecification contains Invalid Value in the request
CM001When CompressTypeValue under the aggregate InputObjectDetail is incorrectThe given request is invalid.CompressTypeValue of InputObjectDetail contains Invalid Value in the request
CM001When LayoutName under the aggregate BatchSpecificationObject is wrongThe given request is invalid.BatchSpecification LayoutName should have value of "Company Service"
CM001More than one BatchSpecificationObject attachments provided in the request.The given request is invalid.More than one BatchSpecificationObject attachments provided in the request.
CM001Input LayoutName should have value of "PCMGBIMatch"The given request is invalid.Input LayoutName should have value of "PCMGBIMatch"
CM001Input LayoutVersion should have value of 1.0The given request is invalid.Input LayoutVersion should have value of 1.0
CM001BatchSpecification LayoutName should have value of "Company Service"The given request is invalid.BatchSpecification LayoutName should have value of "Company Service"
CM003Missing BatchProcessID under the aggregate BatchSpecificationMissing Information in the request.BatchProcessID is missing in the request
CM003Missing ObjectFormatTypeText under the aggregate BatchSpecificationObjectMissing Information in the request.ObjectFormatTypeText of BatchSpecificationObject is missing in the request
CM003BatchSpecificationObject Attachment not provided in the request (Input.csv)Missing Information in the request.BatchSpecificationObject Attachment not provided in the request
CM003InputObject Attachment not provided in the request (Control.xml)Missing Information in the request.InputObject Attachment not provided in the request
CM003Missing ContentObject under the aggregate InputObjectDetailMissing Information in the request.ContentObject of InputObjectDetail is missing in the request
CM003Missing LayoutName under the aggregate BatchSpecificationObjectMissing Information in the request.LayoutName of BatchSpecificationObject is missing in the request
CM003Missing LayoutName under the aggregate InputObjectDetailMissing Information in the request.LayoutName of InputObjectDetail is missing in the request.
CM003Missing ContentObject under the aggregate BatchSpecificationObjectMissing Information in the request.ContentObject of BatchSpecificationObject is missing in the request
CM003ObjectFormatTypeText under the aggregate InputObjectDetail is missingMissing Information in the request.ObjectFormatTypeText of InputObjectDetail is missing in the request
CM004Failed to write to storage device.Internal D&B system error. Please try again or contact your local Customer Service CenterFailed to write to storage device.
CM004Service Batch ID not generatedInternal D&B system error. Please try again or contact your local Customer Service CenterInternal D&B system error. Please try again or contact your local Customer Service Center
SC005User exceeded max records per hourYou have reached maximum limit permitted as per the contract. Please contact your D&B representative or your local Customer Service Center.Hourly limit of batch records exceeded the permitted limit

Feature Notes

On average, submissions with the maximum of 10,000 entries require approximately 5 to 7 minutes for processing. Actual completion of a batch is dependent on the number of pending (queued) requests from all API customers.

This feature may make multiple attempts to locate the D-U-N-S Number, initially using the cleansed input criteria. If a high confidence match is not located, a subsequent search will be performed using the original input criteria, and the results of both attempts will be merged and sorted to provide the highest confidence matches available.

When a multi-line address is provided (e.g. building number, street name and post office box in a single request), this feature will return the proper address for mailing purposes.

What to do Next