Cookies Settings

Loading

dnb-logo
Direct 2.0
Collapse

Bulk Add Monitoring Registration

This feature allows multiple monitoring registration requests to be issued from a single API call, using the Transactional Mini-Batch Service to support small-sized batches (fewer than 100 companies).

Update History

No modifications have been made to this data layer since the initial release.

Quick Start for Small Batches

The process for small batches requires the following steps:

  1. List Preparation - this feature uses the same request format as the single add registration (in XML) concatenated into a single submission.
  2. List Uploads - when you're ready to initiate a batch, submit the list (i.e. ProcessBatch) for processing.
  3. Get Ready for the Results - like the initial list, the results will be in same layout/format as the single add registration (in XML) concatenated into a single result.
  4. Downloading Results - since this feature is synchronous, the response from the ProcessBatch request will contain the registration results.

Feature Request

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

Overview

The list of product request details is packaged in a base 64 encoded and embedded in a typical D&B Direct API call.

To prepare the product request list using XML, concatenate multiple copies of the Add Monitoring Registration request detail package and place within AddMonitoringRegistrationRequest tags before encoding.

The maximum number of product requests for this operation is 100.

The InputObjectDetail LayoutVersion value should match the latest version of the Monitoring service as stated on the Add Monitoring Registration page.

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 feature does not require entitlement for production and trial usage. While this component does not require entitlement, customers will only be permitted to monitor data layers to which they have been 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: Requests to this operation must be submitted in XML format via a POST command regardless of the ObjectFormatTypeText value.

Sample Request
POST https://direct.dnb.com/V2/TransactionalMiniBatch HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: multipart/form-data; boundary="----=_Part_1_3248653.1468334682993"
MIME-Version: 1.0
Authorization: <My Auth Token>
Content-Length: 5316
Host: 10.162.228.116:80
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)


------=_Part_1_3248653.1468334682993
Content-Type: multipart/form-data
Content-Transfer-Encoding: 8bit


<tmb:ProcessBatchRequest xmlns:tmb="http://services.dnb.com/TransactionalMiniBatchV1.0">
         <BatchDetail>
            <ApplicationBatchID>ServiceGovernanceSamples</ApplicationBatchID>
            <MessageTimeStamp>2001-12-17T09:30:47-05:00</MessageTimeStamp>
         </BatchDetail>
         <BatchSpecification>
            <BatchProcessID>TR_BTCH_MNTR_REG</BatchProcessID>
            <BatchPriorityValue>5</BatchPriorityValue>
            <LanguagePreferenceCode>39</LanguagePreferenceCode>
            <CharacterSetPreferenceCode>23423</CharacterSetPreferenceCode>
         </BatchSpecification>
         <InputDetail>
            <InputObjectDetail>
         <ContentObject>
            <xop:Include href="3ce36328:13ba8e236c9:-7dd2" xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
         </ContentObject>
               <ObjectFormatTypeText>XML</ObjectFormatTypeText>
               <LayoutName>AddRegistration</LayoutName>
               <LayoutVersion>2.0</LayoutVersion>
            </InputObjectDetail>
         </InputDetail>
         <OutputSpecification>
            <OutputMethodValue>Online</OutputMethodValue>
            <ObjectFormatTypeText>XML</ObjectFormatTypeText>
         </OutputSpecification>
      </tmb:ProcessBatchRequest>

------=_Part_1_3248653.1468334682993
Content-Type: application/octet-stream; 
	name=attachment-attach-clnstxt1419439046092640363.dat
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="attachment-attach-clnstxt1419439046092640363.dat"; filename="attachment-attach-clnstxt1419439046092640363.dat"

<BatchAddMonitoringRegistrationRequest xmlns:mon="http://services.dnb.com/MonitoringServiceV2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<mon:AddMonitoringRegistrationRequest xmlns:tmb="http://services.dnb.com/TransactionalMiniBatchV1.0">
		<TransactionDetail>
			<ApplicationTransactionID>ServiceGovernanceSamples</ApplicationTransactionID>
			<TransactionTimestamp>2013-06-03T09:30:47Z</TransactionTimestamp>
			<SubmittingOfficeID>345</SubmittingOfficeID>
		</TransactionDetail>
		<AddMonitoringRegistrationRequestDetail>
			<InquiryDetail>
				<DUNSNumber>804735132</DUNSNumber>
				<CountryISOAlpha2Code>US</CountryISOAlpha2Code>
			</InquiryDetail>
			<MonitoringRegistrationSpecification>
				<MonitoringProfileID>12498</MonitoringProfileID>
				<NotificationProfileID>4674</NotificationProfileID>
				<TradeUpIndicator>0</TradeUpIndicator>
				<AutoRenewalIndicator>0</AutoRenewalIndicator>
				<SubjectCategoryText>high</SubjectCategoryText>
				<RegistrationReasonCode>1</RegistrationReasonCode>
			</MonitoringRegistrationSpecification>
			<InquiryReferenceDetail>
				<CustomerReferenceText>ServiceGovernanceSamples-MiniBatch</CustomerReferenceText>
				<CustomerReferenceText/>
				<CustomerReferenceText/>
				<CustomerReferenceText/>
				<CustomerReferenceText/>
				<CustomerBillingEndorsementText>ServiceGovernanceSamples-MiniBatch</CustomerBillingEndorsementText>
			</InquiryReferenceDetail>
		</AddMonitoringRegistrationRequestDetail>
	</mon:AddMonitoringRegistrationRequest>
	<mon:AddMonitoringRegistrationRequest xmlns:tmb="http://services.dnb.com/TransactionalMiniBatchV1.0">
		<TransactionDetail>
			<ApplicationTransactionID>ServiceGovernanceSamples</ApplicationTransactionID>
			<TransactionTimestamp>2013-06-03T09:30:47Z</TransactionTimestamp>
			<SubmittingOfficeID>345</SubmittingOfficeID>
		</TransactionDetail>
		<AddMonitoringRegistrationRequestDetail>
			<InquiryDetail>
				<DUNSNumber>214567885</DUNSNumber>
				<CountryISOAlpha2Code>GB</CountryISOAlpha2Code>
			</InquiryDetail>
			<MonitoringRegistrationSpecification>
				<MonitoringProfileID>12498</MonitoringProfileID>
				<NotificationProfileID>4674</NotificationProfileID>
				<TradeUpIndicator>0</TradeUpIndicator>
				<AutoRenewalIndicator>0</AutoRenewalIndicator>
				<SubjectCategoryText>high</SubjectCategoryText>
				<RegistrationReasonCode>1</RegistrationReasonCode>
			</MonitoringRegistrationSpecification>
			<InquiryReferenceDetail>
				<CustomerReferenceText>ServiceGovernanceSamples-MiniBatch</CustomerReferenceText>
				<CustomerReferenceText/>
				<CustomerReferenceText/>
				<CustomerReferenceText/>
				<CustomerReferenceText/>
				<CustomerBillingEndorsementText>ServiceGovernanceSamples-MiniBatch</CustomerBillingEndorsementText>
			</InquiryReferenceDetail>
		</AddMonitoringRegistrationRequestDetail>
	</mon:AddMonitoringRegistrationRequest>
</BatchAddMonitoringRegistrationRequest>
------=_Part_1_3248653.1468334682993--

Name Characteristics
ProcessBatchRequest Aggregate
ProcessBatchRequest@ServiceVersionNumber Attribute
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

Code used to uniquely identify the business function to be performed (e.g., Match, Cleanse, Match and Cleanse).

ProcessBatchRequest. InputDetail Aggregate, Required

Records information about the input into the Batch process.

ProcessBatchRequest. InputDetail. InputObjectDetail Aggregate, Optional (Array)
ProcessBatchRequest. InputDetail. InputObjectDetail. ContentObject base64Binary, Required

Records or holds the actual file (e.g. data, picture, blob) stored within the attachment.

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

Format of the Content Object (eg: XML, CSV etc)

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.

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

The version of the service for the underlying request.

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

Records information about the output specification.

ProcessBatchRequest. OutputSpecification. OutputMethodValue string, Required

Call Back, FTP, JMS Queue, Web Service

Possible value(s): Online

ProcessBatchRequest. OutputSpecification. ObjectFormatTypeText string, Required

XML,CSV,JSON

Possible value(s): XML

END: ProcessBatchRequest. OutputSpecification /Aggregate
ProcessBatchRequest. BatchReferenceDetail Aggregate, Optional

Records data that allows the customer to specify information to be linked to the request in order to support subsequent process.

ProcessBatchRequest. BatchReferenceDetail. BatchReferenceText string up to 240 chars., Optional(Up to 5x)

A freeform reference string provided by the customer to be linked to the product in order to support subsequent process.

END: ProcessBatchRequest. BatchReferenceDetail /Aggregate
END: ProcessBatchRequest /Aggregate

Endpoint

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

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

Testing

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

Feature Response

Specification

The following is a list of the possible data fields returned by this operation in the XML response. Samples are provided for testing successful and failed retrieval, and to demonstrate the basic layout of a response. The data returned in samples may not represent actual values that this feature will deliver.

The MTOM attachment specified in the ContentObject is a base64 encoded field that, when decoded, will be in the format specified by ObjectFormatTypeText.

NOTE: This operation will send back a response in XML, regardless of the ObjectFormatTypeText value submitted on the request.

Sample Response
HTTP/1.1 200 OK
Via: 1.1 dbslsigwbv03 (), 1.1 dbslsegwbv03 ()
Connection: Keep-Alive
X-CorrelationID: Id-69be905720fe03004bbc06009e042776 0; Id-6abe9057a99a00006b6c02007c105c61 0
Date: Thu, 21 Jul 2016 12:22:02 GMT
X-Powered-By: Servlet/2.5 JSP/2.1
Content-Type: multipart/related; boundary=MIME_Boundary; 	start=8259981961911062378-56316fa7.1560d4d01aa.-61da; 	type="application/xop+xml"; start-info="text/xml"
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Length: 1114

--MIME_Boundary
Content-ID: 8259981961911062378-56316fa7.1560d4d01aa.-61da
Content-Type: application/xop+xml;
	charset="utf-8";
	type="text/xml"

<?xml version="1.0" encoding="utf-8"?>
<tran:ProcessBatchResponse ServiceVersionNumber="2" xmlns:tran="http://services.dnb.com/TransactionalMiniBatchV1.0"> <BatchDetail> <ApplicationBatchID>ServiceGovernanceSamples</ApplicationBatchID> <ServiceBatchID>Id-a04d9057f2960100569906005b0e8a7b-1</ServiceBatchID> <MessageTimeStamp>2001-12-17T09:30:47-05:00</MessageTimeStamp> </BatchDetail> <BatchResult> <SeverityText>Information</SeverityText> <ResultID>CM000</ResultID> <ResultText>Success</ResultText> </BatchResult> <OutputDetail> <OutputObjectDetail> <ObjectFormatTypeText>XML</ObjectFormatTypeText> <LayoutName>AddRegistration</LayoutName> <ContentObject> <inc:Include href="cid:-5673d010:1560b36a40f:-196b" xmlns:inc="http://www.w3.org/2004/08/xop/include"/> </ContentObject> </OutputObjectDetail> </OutputDetail> <BatchProcessSummary> <ExectuionTimeSummary> <BatchRequestCreatedTimeStamp>2001-12-17T09:30:47-05:00</BatchRequestCreatedTimeStamp> <BatchReceivedTimeStamp>2001-12-17T09:30:47-05:00</BatchReceivedTimeStamp> <ActualProcessCompletionTimestamp>2016-07-21T08:22:11</ActualProcessCompletionTimestamp> </ExectuionTimeSummary> <RecordSummary> <TotalInputRecordCount>2</TotalInputRecordCount> <TotalOutputRecordCount>2</TotalOutputRecordCount> <TotalPassedRecordCount>2</TotalPassedRecordCount> <TotalFailedRecordCount>0</TotalFailedRecordCount> </RecordSummary> </BatchProcessSummary> </tran:ProcessBatchResponse>

--MIME_Boundary
Content-ID: <56316fa7:1560d4d01aa:-61ad>
Content-Type: application/octet-stream

<BatchOrderProductResponse xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"> <ns2:AddMonitoringRegistrationResponse ServiceVersionNumber="?" xmlns:ns2="http://services.dnb.com/MonitoringServiceV2.0" xmlns:ns3="http://services.dnb.com/TransactionFaultV2.0" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <TransactionDetail> <ApplicationTransactionID>ServiceGovernanceSamples</ApplicationTransactionID> <ServiceTransactionID>Id-68bb9057d47a0200526309002836a65b-2</ServiceTransactionID> <TransactionTimestamp>2013-06-03T09:30:47Z</TransactionTimestamp> </TransactionDetail> <TransactionResult> <SeverityText>Information</SeverityText> <ResultID>CM026</ResultID> <ResultText> Request accepted.Processing pending.</ResultText> </TransactionResult> <AddMonitoringRegistrationResponseDetail> <InquiryDetail> <DUNSNumber>804735132</DUNSNumber> <CountryISOAlpha2Code>US</CountryISOAlpha2Code> </InquiryDetail> <MonitoringRegistrationDetail> <DUNSNumber>804735132</DUNSNumber> <MonitoringProfileID>12498</MonitoringProfileID> <NotificationProfileID>4674</NotificationProfileID> <StartDate>2016-07-21</StartDate> <EndDate>2017-09-12</EndDate> </MonitoringRegistrationDetail> <InquiryReferenceDetail> <CustomerReferenceText>ServiceGovernanceSamples-MiniBatch</CustomerReferenceText> <CustomerBillingEndorsementText>ServiceGovernanceSamples-MiniBatch</CustomerBillingEndorsementText> </InquiryReferenceDetail> </AddMonitoringRegistrationResponseDetail> </ns2:AddMonitoringRegistrationResponse> <ns2:AddMonitoringRegistrationResponse ServiceVersionNumber="?" xmlns:ns2="http://services.dnb.com/MonitoringServiceV2.0" xmlns:ns3="http://services.dnb.com/TransactionFaultV2.0" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <TransactionDetail> <ApplicationTransactionID>ServiceGovernanceSamples</ApplicationTransactionID> <ServiceTransactionID>Id-68bb9057d37a020052630900cc6f3df8-2</ServiceTransactionID> <TransactionTimestamp>2013-06-03T09:30:47Z</TransactionTimestamp> </TransactionDetail> <TransactionResult> <SeverityText>Information</SeverityText> <ResultID>CM026</ResultID> <ResultText> Request accepted.Processing pending.</ResultText> </TransactionResult> <AddMonitoringRegistrationResponseDetail> <InquiryDetail> <DUNSNumber>214567885</DUNSNumber> <CountryISOAlpha2Code>GB</CountryISOAlpha2Code> </InquiryDetail> <MonitoringRegistrationDetail> <DUNSNumber>214567885</DUNSNumber> <MonitoringProfileID>12498</MonitoringProfileID> <NotificationProfileID>4674</NotificationProfileID> <StartDate>2016-07-21</StartDate> <EndDate>2017-09-12</EndDate> </MonitoringRegistrationDetail> <InquiryReferenceDetail> <CustomerReferenceText>ServiceGovernanceSamples-MiniBatch</CustomerReferenceText> <CustomerBillingEndorsementText>ServiceGovernanceSamples-MiniBatch</CustomerBillingEndorsementText> </InquiryReferenceDetail> </AddMonitoringRegistrationResponseDetail> </ns2:AddMonitoringRegistrationResponse> </BatchOrderProductResponse>
--MIME_Boundary--

Name Characteristics
ProcessBatchResponse Aggregate
ProcessBatchResponse @ServiceVersionNumber Attribute
ProcessBatchResponse { BatchDetail Aggregate, Required

Records information necessary to return a particular response.

ProcessBatchResponse { 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.

ProcessBatchResponse { BatchDetail { ServiceBatchID string, up to 64 chars, Required

A number assigned by the composite service (e.g., MatchCleanseService, GHM) which is used to uniquely identify a batch request.

ProcessBatchResponse { BatchDetail { MessageTimeStamp Element
END: ProcessBatchResponse } BatchDetail /Aggregate
ProcessBatchResponse { BatchResult Aggregate, Optional

Records information about the result of the process.

ProcessBatchResponse { BatchResult { SeverityText string, Required

Text that records the criticality of the outcome, e.g., Information, Warning, Error, Fatal.

ProcessBatchResponse { BatchResult { ResultID string, up to 32 chars, Required

An alphanumeric string that uniquely identifies the outcome of the batch.

ProcessBatchResponse { BatchResult { ResultText string, up to 512 chars, Optional

Text that explains the outcome of the batch.

ProcessBatchResponse { BatchResult { ResultMessage Aggregate, Optional (Array)

An aggregate that can repeat multiple times to record textual data that expands on the ResultID and ResultText to provide additional information to the user regarding the status of the batch. If the status implies that there is a problem this may also provide guidance to the user on how to address it.

ProcessBatchResponse { BatchResult { ResultMessage { ResultDescription string, up to 512 chars, Required

Text that describes the additional information regarding the outcome of the batch.

END: ProcessBatchResponse } BatchResult } ResultMessage /Aggregate
END: ProcessBatchResponse } BatchResult /Aggregate
ProcessBatchResponse { OutputDetail Aggregate, Optional

Records information about the output of the Batch process.

ProcessBatchResponse { OutputDetail { OutputObjectDetail Aggregate, Optional (Array)
ProcessBatchResponse { OutputDetail { OutputObjectDetail { ObjectFormatTypeText string, up to 5 chars, Required

Describes the format of the attached file, e.g., txt, pdf, html.

Possible values: JSON; XML

ProcessBatchResponse { OutputDetail { OutputObjectDetail { 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.

ProcessBatchResponse { OutputDetail { OutputObjectDetail { ContentObject base64Binary, Required

Records or holds the actual file (e.g. data, picture, blob) stored within the attachment.

END: ProcessBatchResponse } OutputDetail } OutputObjectDetail /Aggregate
END: ProcessBatchResponse } OutputDetail /Aggregate
ProcessBatchResponse { BatchProcessSummary Aggregate, Optional

Records information about the process time and the number of records processed.

ProcessBatchResponse { BatchProcessSummary { ExecutionTimeSummary Aggregate, Optional

Records information about the process time and completion time.

ProcessBatchResponse { BatchProcessSummary { ExecutionTimeSummary { BatchRequestCreatedTimeStamp dateTime, Required

The date and time when the batch request was created by the submitting application.

ProcessBatchResponse { BatchProcessSummary { ExecutionTimeSummary { BatchReceivedTimeStamp dateTime, Optional

The date and time when the batch request was received by the service.

ProcessBatchResponse { BatchProcessSummary { ExecutionTimeSummary { ActualProcessCompletionTimestamp dateTime, Optional

The date and time when the requested process (i.e., match, cleanse, cleansematch) was actually completed by the service.

END: ProcessBatchResponse } BatchProcessSummary } ExecutionTimeSummary /Aggregate
ProcessBatchResponse { BatchProcessSummary { RecordSummary Aggregate, Optional

Records information about the number of input and output records, and the count of the number of records which have passed and failed the requested process.

ProcessBatchResponse { BatchProcessSummary { RecordSummary { TotalInputRecordCount integer, Optional

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

ProcessBatchResponse { BatchProcessSummary { RecordSummary { TotalOutputRecordCount integer, Optional

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

ProcessBatchResponse { BatchProcessSummary { RecordSummary { TotalPassedRecordCount string, Optional

A numeric value denoting the total number of records which have passed the requested process.

ProcessBatchResponse { BatchProcessSummary { RecordSummary { TotalFailedRecordCount string, Optional

A numeric value denoting the total number of records which have failed the requested process.

END: ProcessBatchResponse } BatchProcessSummary } RecordSummary /Aggregate
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: CM002, CM004, and SC001-SC008.

NOTE: Each individual request will return a response code in the AddMonitoringRegistrationResponse TransactionResult ResultID field. Refer to Data Layer/Field Monitoring for a list of valid response codes.

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 Small batch request are recorded as a series of individual requests of the underlying request type. Therefore, customer online usage (OLUS) reports will display multiple entries for each batch submitted.

Feature Notes

The results from this feature will be a base 64 encoded concatenated block of separate Add Monitoring Registration responses (based on the format specified on the request).

Response codes will be returned for the overall result, as well as, for each individual product request.

What to do Next