d&b direct 2.0 custom product service · d&b...
TRANSCRIPT
D&B DirectAPI Documentation for
Custom Product Service
Version 2.0 (API) / 2.0 (Service)
D&B Direct is a trademark or registered trademark of Dun and Bradstreet, Incorporated. Other trademarks
used herein are the trademarks or registered trademarks of their respective owners.
This document is a work of authorship that belongs to Dun and Bradstreet, Incorporated and is protected
by United States and foreign copyright laws and international copyright treaties. The use of the software
and this Documentation is governed by the Dun and Bradstreet Incorporated software license agreement.
D&B DOES NOT GUARANTEE OR WARRANT SYSTEMS AVAILABILITY OR PERFORMANCE IN ACCORDANCE
WITH THE FIGURES WITHIN THIS DOCUMENT, NOR DOES D&B ACCEPT ANY LIABILITY FOR DAMAGES
WHICH MAY BE SUFFERED AS A RESULT OF PLACING ANY RELIANCE ON THESE FIGURES. D&B RESERVES
THE RIGHT TO AMEND THIS DOCUMENT AT ANY TIME AND WILL ADVISE THE CUSTOMER ACCORDINGLY OF
ANY SUCH AMENDMENTS OR CHANGES.
©Dun & Bradstreet, Inc. 2014. All rights reserved
ContentsThese pages provide business overviews; explaining requirements and the business elements that will bedelivered. For suggested uses of the API components, please refer to the Solutions menu option on thedeveloper.dnb.com home page.
Title / Overview Link
Custom Product Selection
These pages provide the technical specifications that a developer will need to obtain information usingD&B Direct.
Service Operation / SOAP Resource / REST
n/a [Authentication Process] POST Authentication
Custom Product Service OrderProduct GET organizations/{DUNS}/products/{productID}
RetrieveProduct GET assets/{assetid}/{productid}
Service History
Version Date Interface(s)
Change(s)
2.0 August22, 2014
SOAP/REST Custom data layers are now accepted by the monitoring service. UseGetProductCatalog for list of elements which will be monitored.
D&B Direct API Documentation Service History
©Dun & Bradstreet, Inc. 2014 3
About this DocumentationThe D&B Direct 2.0 API Reference materials are organized into product, feature, service and operation pages.Throughout the documentation, certain items are marked as eligible for custom products and/or for inclusionin the monitoring process.
Key Concepts
Business Elements vs. Data Fields
The D&B Direct API has been designed to efficiently deliver information, and as a result, multiple businesselements are often delivered in the same data field (with separate attributes signaling the specific contents ofa data field).
The documentation highlights the business elements (i.e. business-oriented labels) on product pages; and thedata fields (i.e. technical, variable-like names used within the delivery packages) on operation pages -- withthe business elements linked to the corresponding data field for each available implementation.
Data Layers
The D&B Direct API delivers information in data layers, some of which have multiple levels. For the purpose ofthis documentation, the term Product is used to represent a given level for a data layer.
For example, "Detailed Company Profile" is the Data Layer, while "Detailed Company Profile - Enhanced" willbe referred to as a Product.
Custom Products
D&B Direct offers a customization service that allows for up to eight pre-configured products to be deliveredthrough the API web service. Throughout the documentation, business elements and data fields which areeligible for inclusion in a custom product are designated with a [C] marker.
Service Versions
It is important to note that D&B Direct 2.x implements version control at the service level, in addition to theAPI level. For example, the current version of the Assessment Product Service is Version 2.0 (API) / 3.0 (Service).
D&B Direct services will be updated (major and minor version changes) without a API version change.Following the example given, it will be possible for the Assessment Product Service to change to Version 2.0
D&B Direct API Documentation About this Documentation
©Dun & Bradstreet, Inc. 2014 4
(API) / 3.1 (Service) or Version 2.0 (API) / 4.0 (Service) based on the significance of the changes made to theservice.
Product Pages
These are non-technical pages that describe the information (i.e. business elements) returned by the data-oriented operations. In addition, the requirements and options for requesting data are mentioned.
Feature Pages
These are also non-technical pages, but explain the use of operations that provide a function (e.g. search) andoften return the items (i.e. D-U-N-S Number) required to request data products.
Service Pages
These are technical pages that explain what operations a given API web service provides, the correct versionand endpoints, WSDL location (for SOAP), and how to download samples and data dictionaries specific to theservice. While services are not applicable for REST implementations, the documentation is organized aroundthem for consistency.
Operation Pages
These are also technical pages, but describe (for each available implementation method) the individualfunctions provided by a service, listing the input field names and requirements, and the output with datafields (including data type, size, description and possible values).
Release Histories
Whenever an operation is enhanced (or a minor correction is made), a notation will be added to a section onthe bottom of the affected SOAP/REST operation page. If the change is significant and results in a versionchange, the release history will maintain a link to the documentation for the previous version(s).
Getting Started
While the API Reference documentation provides extensive details on each operation and data layer, for moresummarized explanations of common tasks/uses refer to the collection of How To Guides.
D&B Direct API Documentation Product Pages
©Dun & Bradstreet, Inc. 2014 5
Custom Product SelectionD&B Direct allows the creation of custom collections of data elements per customer account. Customcollections are configured by D&B Sales Associates, and then made available through API calls.
Product Configuration
Throughout the D&B Direct documentation, Business Element and Response Data Field items will bedesignated with a [C] if they may be included in a Custom Product.
D&B Sales Associates may be provided lists of either Business Element or Response Data Field items (the latteris preferred) for pricing and configuration of up to six Custom Products. Customers may also designate fieldsin a given Custom Product to be "required." When any of these required fields (for a given D-U-N-S Number)are not available, the request will return an error code.
For data items where previous calculations are available (e.g. Financial Stress Score and Commercial CreditScore), be sure to mention the version number to the D&B Sales Associate if an alternate calculation isrequired.
Once configured, the D&B Sales Associate will provide a Product Code designated for the new CustomProduct. Each custom product configuration is only available to the customer account to which it is assigned.
Requirements & Options
When requesting a Custom Product (that excludes small businesses or company principals), a valid D-U-N-SNumber for a company, its country code, and the appropriate product code will be required. If this informationis not available, refer to obtaining a company D-U-N-S Number for assistance. A trade up option exists torequest data for the headquarters when the requested organization is a branch.
When ordering information for organizations located in Germany, customers are required to provide a validorder reason code. A list of possible values is included on the respective SOAP or REST operation page.
When requesting a Custom Product for a small business, you will be required to supply either valid D-U-N-SNumber or subject identification number (Subject ID) for a small business, a country code of "US", and theappropriate product code. Subject IDs for organizations may be obtained by using the small business option inthe On-Demand Entity Identification feature.
When requesting a Custom Product for a company principal, you will be required to supply the valid D-U-N-SNumber for a company, principal identification number (Principal ID), and the appropriate product code.Principal IDs for individual company officers may be obtained by using the Search & Build-a-List - Contacts(Plus Email Lookup) feature.
D&B Direct API Documentation Custom Product Selection
©Dun & Bradstreet, Inc. 2014 6
Note: The product code for D&B Direct 2.0 - Custom Product will be CST_PRD_1 to CST_PRD_6. Thisproduct may be included in the Monitoring process.
Business Elements
The business elements returned in a custom product vary based on customer selection.
Exception: Custom Product requests will not return a set of standard elements for the company requested.These elements may be included, by request, during the configuration process.
When any of the business elements that were designated as "required" when the Custom Product wasconfigured do not contain a value for a particular company, an error code will be returned, and yourorganization will not incur a usage credit for the request.
The Product Availability Lookup feature may be utilized to determine if a particular D&B Direct customproduct is available for a D-U-N-S Number.
Additional Details
The availability of certain scores delivered by this product may be limited due to a lack of sufficient companyor industry specific data to perform the calculations.
Access to this information is provided on a metered basis; and will require data layer entitlement prior to usein the production environment. A built-in feature exists to prevent duplicate billing when multiple requestswith the same D-U-N-S Number and product code are submitted on the same calendar day (which is based onEastern Standard Time [GMT-5]).
An option exists to retain the results from all successful requests for this product in a Product Request Archive,which may be retrieved without incurring additional usage charges.
Monitoring Custom Products
To determine which data fields within a custom product will trigger a Monitoring Change Notice, issue arequest to the GetProductCatalog function in the Product Catalog Serviceand inspect theMonitorableElementDetail list that is returned.
Technical Specification
For details on how to obtain this data layer, please refer to the Custom.OrderProduct (SOAP) orCustom.OrderProduct (REST) page.
D&B Direct API Documentation Business Elements
©Dun & Bradstreet, Inc. 2014 7
Custom Product ServiceVersion 2.0 (API) / 2.0 (Service)
Functions
This D&B Direct service includes the following functionality. The respective SOAP and/or REST pages providetechnical details including input parameters, responses and sample requests.
Function Operation /SOAP
Resource / REST
Deliver a data layer. (see "Product (Data Layer) Details")
OrderProduct() GET organizations/{DUNS}/products/{productID}
Deliver copies of previously ordered products. RetrieveProduct() GET assets/{assetid}/{productid}
The Order Product function provides pre-configured custom data layers for a specific company, and requires aD-U-N-S Number, country code and one of the custom product codes {productID}.
The Retrieve Product function can be used to fetch previously obtained copies of data layers from the ProductRequest Archive. The default archival period is 120 days, unless extended (up to 365 days) when the data layerwas originally requested.
Product (Data Layer) Details
The following D&B products may be obtained by using this service. All D&B Direct product codes are casesensitive. The Product pages provide an overview, including the business elements (and definitions) delivered.
Title / Overview Link Product Code{productID}
D&B Direct 2.0 - Custom Product CST_PRD_1 to CST_PRD_6
Interfaces & Endpoints
D&B Direct implements version control at the web service level, in addition to the API level. This D&B Direct2.0 {version} of the Custom Product Service is 2.0. When contacting D&B customer support, please provideboth the API and Service version numbers. The following table(s) identify version-specific access points for theavailable API interfaces.
SOAP
Endpoint https://maxcvservices.dnb.com/CustomProduct/V{version}
WSDL* http://developer.dnb.com/docs/2.0/custom/2.0/CustomProductService.zip
D&B Direct API Documentation Custom Product Service
©Dun & Bradstreet, Inc. 2014 8
*There may be operations defined in the WSDL that are not available to D&B Direct customers at this time.
REST
OrderProduct GET https://maxcvservices.dnb.com/V{version}/organizations/{DUNS}/products/{productID}
OrderProduct (bySubject ID)
GET https://maxcvservices.dnb.com/V{version}/organizations/subjectid-{subjectID}/products/{productID}
RetrieveProduct GET https://maxcvservices.dnb.com/V{version}/assets/{assetID}/{productID}
Note: While "organizations" is part of the REST OrderProduct URL, there is no service by this name.D&B Direct product-related calls have a similar structure; however, the {version} component is based onthe service to which a given product is associated.
D&B Direct API calls must be made using Secured Socket Layers (SSL) as reflected in the preceding table(s).
D&B Direct API Documentation Interfaces & Endpoints
©Dun & Bradstreet, Inc. 2014 9
Custom:OrderProduct (REST)This operation -- part of the Custom Product Service -- provides access to (up to six) D&B Direct 2.0 - CustomProduct using product codes CST_PRD_1 to CST_PRD_6.
Authentication & Endpoint
D&B Direct web services require authentication, and the data environment (i.e. production, trial or sandbox) isdetermined by the credentials submitted with each API request. Refer to the service page for the correct versionof the operation.
Endpoint
GET https://maxcvservices.dnb.com/V{version}/organizations/{DUNS}/products/{productID}
Request Parameters
The following parameters are accepted by this operation; however, the requirements for a specific requestmay differ based the product being requested. Please refer to the downloadable data dictionary (filterable byproduct code) to determine which fields are applicable.
The default value for ArchiveProductOptOutIndicator is 'true', indicating that the request will NOT beautomatically archived.
Name Characteristics
{version} Element
ApplicationTransactionID string, up to 64 chars, Optional
A number assigned by the calling application to uniquely identify this request.
TransactionTimestamp DateTimestamp, Optional
The date and time when this request was created. When the request is from
an intermediary, such as a workflow manager or service bus, this is the date
and time when the message was sent to the D&B function, i.e., the date and
time when the xml document was created by the requesting intermediary.
SubmittingOfficeID string, up to 64 chars, Optional
A number that identifies the system or the software application from where
this request originated. / A number used to uniquely identfy the D&B
business segment or delivery channel from where this request originated.
D&B Direct API Documentation Custom:OrderProduct (REST)
©Dun & Bradstreet, Inc. 2014 10
Name Characteristics
{DUNS} string, up to 15 chars Pattern: {([0-9a-zA-Z]*)}, Optional
The D-U-N-S Number is D&B's identification number, which provides unique
identification of this organization, in accordance with the Data Universal
Numbering System (D-U-N-S).
{subjectID} string, up to 15 chars, Optional
A number uniquely identifying the inquired subject within the D&B
Worldwide Network.
CountryISOAlpha2Code string, at least 2 chars up to 2 chars, Optional
The two-letter country code, defined in the ISO 3166-1 scheme published by
International Organization for Standardization (ISO)identifying the country of
the inquired subject.
PrincipalIdentificationNumberTypeCode Element
PrincipalIdentificationNumber string, Optional
A number assigned by an external body or by D&B which either uniquely
identifies or helps to identify an individual.
{productID} string, Required
An alphanumeric string that uniquely identifies the product being requested.
LanguagePreferenceCode integer, up to 7 digits, Optional
A D&B code value that defines the language in which the customer wants
this product to be rendered.
CharacterSetPreferenceCode integer, up to 7 digits, Optional
A D&B code value denoting the set of graphic symbols (e.g., alphabet letter,
pictograph) in which the product is to be rendered, e.g., Unicode.
ProductFormatPreferenceCode integer, up to 7 digits, Optional
D&B Direct API Documentation Request Parameters
©Dun & Bradstreet, Inc. 2014 11
Name Characteristics
TradeUpIndicator boolean, Optional
When 'true' indicates that the customer has requested that D&B return the
data for the Headquarters when the requested organization is a Branch.
When 'false' indicates that the customer has not requested that D&B return
the data for the Headquarters when the requested organization is a Branch;
however as this is the assumed condition there is no requirement to create
this tag to represent this fact. Note: There are D&B WorldWide Network
operations where the Headquarters information will be returned
automatically, regardless of the customer request.
OrderReasonCode integer, up to 7 digits, Optional
Possible values: 6332 [Credit Decision]; 6333 [Assessment of credit solvency
for intended business connection]; 6334 [Assessment of credit solvency for
ongoing business connection]; 6335 [Debt Collection]; 6336 [Commercial
Credit Insurance]; 6337 [Insurance Contract]; 6338 [Leasing Agreement]; 6339
[Rental Agreement]
ArchiveProductOptOutIndicator boolean, Optional
When 'true' indicates that the product being ordered is not to be stored.
When 'false' indicates that the product being ordered is to be stored; however
as this is the assumed condition there is no requirement to create this tag to
represent this fact.
ExtendArchivePeriodIndicator boolean, Optional
When 'true' the duration to archive the data is to be extended. Note: There is
an additional cost for extending the archival period of the data purchased.
When 'false' the duration to archive the data is not to be extended.
PortfolioAssetContainerID long, Optional
A number used to uniquely identify the location where this product is to be
stored.
D&B Direct API Documentation Request Parameters
©Dun & Bradstreet, Inc. 2014 12
Name Characteristics
CustomerReferenceText string, up to 240 chars, Optional
A freeform reference string provided by the customer to be linked to the
product in order to support subsequent order reconciliation.
CustomerBillingEndorsementText string, at least 1 chars, up to 240 chars, Optional
Text that is filled in by customer and commonly contains requesting individual
or department name, or customer's own account/reference number and/or
name for the case on which the product was provided.This text is a reference
used during the billing process.
Testing / Sandbox
This operation will return results in the D&B Direct sandbox (test) environment only when a test D-U-N-SNumber is provided in the request parameters.
Response Data Fields
The following is a list of the possible data fields returned by this operation in the JSON response. The specificdata fields pre-configured for each custom data product will located in the response package as noted.
Name Characteristics
OrderProductResponse Aggregate
OrderProductResponse@ServiceVersionNumber
Attribute
OrderProductResponse { TransactionDetail
Aggregate, Required
Records information necessary to process a particular request. Examples of a
request is the ordering of a product.
OrderProductResponse { TransactionDetail { ApplicationTransactionID
string up to 64 chars., Optional
A number assigned by the calling application to uniquely identify this request.
OrderProductResponse { TransactionDetail { ServiceTransactionID
string up to 64 chars., Required
A number assigned by the D&B service to uniquely identify this transaction.
D&B Direct API Documentation Testing / Sandbox
©Dun & Bradstreet, Inc. 2014 13
Name Characteristics
OrderProductResponse { TransactionDetail { TransactionTimestamp
DateTimestamp, Required
The date and time when this request was submitted or the date and time when
the requesting intermediary, such as a workflow manager or service bus, sent the
message to the D&B function, i.e., the date and time when the xml document
was created by the requesting intermediary.
End: OrderProductResponse }TransactionDetail
/Aggregate
OrderProductResponse { TransactionResult
Aggregate, Required
An aggregate that can repeat multiple times to record the different outcomes of
the transaction.
OrderProductResponse { TransactionResult { SeverityText
string up to 16 chars., Required
Text that records the criticality of the outcome, e.g., Information, Warning, Error,
Fatal.
OrderProductResponse { TransactionResult { ResultID
string up to 32 chars., Required
An alphanumeric string that uniquely identifies the outcome of the transaction.
OrderProductResponse { TransactionResult { ResultText
string up to 512 chars., Optional
Text that explains the outcome of the transaction.
OrderProductResponse { TransactionResult { ResultMessage
Aggregate, Optional (Infinite)
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 transaction. If the status implies that there is a
problem this may also provide guidance to the user on how to address it.
OrderProductResponse { TransactionResult { ResultMessage{ ResultDescription
string up to 512 chars., Required
Text that describes the additional information regarding the outcome of the
transaction.
End: OrderProductResponse }TransactionResult } ResultMessage
/Aggregate
End: OrderProductResponse }TransactionResult
/Aggregate
OrderProductResponse { OrderProductResponseDetail
Aggregate, Optional
Records the data being returned to the customer as a result of a product request.
D&B Direct API Documentation Response Data Fields
©Dun & Bradstreet, Inc. 2014 14
Name Characteristics
OrderProductResponse { OrderProductResponseDetail { InquiryDetail
Aggregate, Required
Records data that allows the customer to specify identifying information about
the subject being inquired, e.g., the DUNS Number, the address, the telephone
number.
OrderProductResponse { OrderProductResponseDetail { InquiryDetail { DUNSNumber
string up to 15 chars. Pattern: {([0-9a-zA-Z]*)}., Optional
The D&B's identification number, which provides unique identification of the
inquired organization, in accordance with the Data Universal Numbering System
(D-U-N-S).
OrderProductResponse { OrderProductResponseDetail { InquiryDetail { SubjectID
string up to 15 chars., Optional
A number uniquely identifying the inquired subject within the D&B Worldwide
Network.
OrderProductResponse { OrderProductResponseDetail { InquiryDetail { CountryISOAlpha2Code
string at least 2 chars. up to 2 chars., Optional
The two-letter country code, defined in the ISO 3166-1 scheme published by
International Organization for Standardization (ISO)identifying the country of the
inquired subject.
OrderProductResponse { OrderProductResponseDetail { InquiryDetail { PrincipalIdentificationNumberDetail
Aggregate, Optional (Infinite)
An entry loop which can repeat multiple times to allow the recording of several
different identifiers issued by organizations to uniquely identify the principal. The
issuing organization may be a Registration Authority, Government Department or
Commercial Enterprise, e.g., the Social Security Administration department.
OrderProductResponse { OrderProductResponseDetail { InquiryDetail { PrincipalIdentificationNumberDetail@DNBCodeValue
Attribute
OrderProductResponse { OrderProductResponseDetail { InquiryDetail { PrincipalIdentificationNumberDetail@DNBCodeTableNumber
Attribute
OrderProductResponse { OrderProductResponseDetail { InquiryDetail { PrincipalIdentificationNumberDetail@TypeText
Attribute
D&B Direct API Documentation Response Data Fields
©Dun & Bradstreet, Inc. 2014 15
Name Characteristics
OrderProductResponse { OrderProductResponseDetail { InquiryDetail { PrincipalIdentificationNumberDetail{ PrincipalIdentificationNumber
string, Optional
A number assigned by an external body or by D&B which either uniquely
identifies or helps to identify an individual.
End: OrderProductResponse }OrderProductResponseDetail }InquiryDetail }PrincipalIdentificationNumberDetail
/Aggregate
End: OrderProductResponse }OrderProductResponseDetail }InquiryDetail
/Aggregate
OrderProductResponse { OrderProductResponseDetail { Product
Aggregate, Required
Records data about the product ordered by the customer and data about the
organization on which the customer has placed this order.
OrderProductResponse { OrderProductResponseDetail { Product { DNBProductID
string up to 64 chars., Optional
An alphanumeric string that uniquely identifies this product.
OrderProductResponse { OrderProductResponseDetail { Product { LanguageCode
integer up to 7 digits., Optional
A D&B code value that defines the language in which the requested product is
fulfilled.
OrderProductResponse { OrderProductResponseDetail { Product { Organization
Aggregate, Required
Records data about an organization, a legal or commercial entity established to
provide products and/or services in the marketplace or to the community.
Contents of "Organization PCMAggregate
Contents of "Organization PCM Aggregate
Possible values: Contents of "Organization PCM Aggregate
END: OrderProductResponse }OrderProductResponseDetail }Product } Organization
/Aggregate
OrderProductResponse { OrderProductResponseDetail { Product { ArchiveDetail
Aggregate, Optional
Records data about the archival details of the product requested.
OrderProductResponse { OrderProductResponseDetail { Product { ArchiveDetail { PortfolioAssetID
PortfolioAssetIDType, Optional
A number used to uniquely identify this product in the location where it is stored.
D&B Direct API Documentation Response Data Fields
©Dun & Bradstreet, Inc. 2014 16
Name Characteristics
OrderProductResponse { OrderProductResponseDetail { Product { ArchiveDetail { PortfolioAssetContainerID
long, Optional
A number used to uniquely identify the location where this product is stored.
End: OrderProductResponse }OrderProductResponseDetail }Product } ArchiveDetail
/Aggregate
OrderProductResponse { OrderProductResponseDetail { Product { CopyrightNoticeText
string up to 128 chars., Optional
Text that specifies the underlying claim to copyright ownership of this product.
End: OrderProductResponse }OrderProductResponseDetail }Product
/Aggregate
OrderProductResponse { OrderProductResponseDetail { InquiryReferenceDetail
Aggregate, Optional
Records data that allows the customer to specify information to be linked to the
request in order to support subsequent order reconciliation.
OrderProductResponse { OrderProductResponseDetail { InquiryReferenceDetail { CustomerReferenceText
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 order reconciliation.
OrderProductResponse { OrderProductResponseDetail { InquiryReferenceDetail { CustomerBillingEndorsementText
string at least 1 chars. up to 240 chars., Optional
Text that is filled in by customer and commonly contains requesting individual or
department name, or customer's own account/reference number and/or name
for the case on which the product was provided.This text is a reference used
during the billing process.
End: OrderProductResponse }OrderProductResponseDetail }InquiryReferenceDetail
/Aggregate
End: OrderProductResponse }OrderProductResponseDetail
/Aggregate
End: OrderProductResponse /Aggregate
Lists of possible values (when present) are subject to change. Additional values not presented in this documentation may be delivered
in the response and should be anticipated in any implementation.
Abbreviated Territory Names
When present, the Territory Abbreviated Name field will contain local abbreviations, which may be based onstandard designations. For companies domiciled in the United States or Canada, this field will contain the
D&B Direct API Documentation Abbreviated Territory Names
©Dun & Bradstreet, Inc. 2014 17
second component of ISO 3166-2 codes. For example, the ISO 3166-2:US code for New Jersey is "US-NJ" andthe value "NJ" will be delivered in this field. Similarly, the ISO 3166-2:CA code for Ontario is "CA-ON" and thevalue "ON" will be delivered in this field.
Language/Character Sets
The text contained within D&B Direct 2.0 data layers is returned in English. Several reports, including theD&B Business Information Report (BIR), provide additional language options. Data layers are encoded usingthe ISO 8859-1 character set standard (sometimes referred to as Latin-1), EXCEPT when the organization isdomiciled in the Czech Republic (CZ), Hungary (HU), Poland (PL) or Slovakia (SK). Data from these markets iscurrently encoded using the ISO 8859-2 character set standard.
Response Codes
Successful service requests will return a CM000 response code. Otherwise, one of the D&B Direct standardresponse codes will be returned.
This operation may return the following response codes: CM001-CM005, CM007-CM012, CM014, CM017,CM018, PD001, PD003, PD005, PD006, PD015, PD016, and SC001-SC012.
Product (Data Layer) Details
Title / Overview Link Product Code Countries
D&B Direct 2.0 - Custom Product CST_PRD_1 to CST_PRD_6 varies
Samples (Download)
Request and response samples are available for this D&B Direct web services. The samples may cover avariety of scenarios (when applicable) and are designed for use in the test environment.
Custom Product Service
Samples http://developer.dnb.com/docs/2.0/custom/2.0/DnB-Custom.zip
Related Topics
{productservice}:RetrieveProduct (REST)
D&B Direct API Documentation Language/Character Sets
©Dun & Bradstreet, Inc. 2014 18
Custom:OrderProduct (SOAP)This operation -- part of the Custom Product Service -- provides access to (up to six) D&B Direct 2.0 - CustomProduct using product codes CST_PRD_1 to CST_PRD_6.
Authentication, Endpoint & WSDL
D&B Direct web services require authentication, and the data environment (i.e. production, trial or sandbox) isdetermined by the credentials submitted with each API request. Refer to the service page for the correct versionof the operation.
Endpoint
https://maxcvservices.dnb.com/CustomProduct/V{version}
Request Parameters
The following parameters are accepted by this operation; however, the requirements for a specific requestmay differ based the product being requested. Please refer to the downloadable data dictionary (filterable byproduct code) to determine which fields are applicable.
The default value for ArchiveProductOptOutIndicator is 'true', indicating that the request will NOT beautomatically archived.
Name Characteristics
OrderProductRequest Aggregate
OrderProductRequest@ServiceVersionNumber
Attribute
OrderProductRequest.TransactionDetail
Aggregate, Optional
Records information necessary to process this request.
OrderProductRequest.TransactionDetail.ApplicationTransactionID
string, up to 64 chars, Optional
A number assigned by the calling application to uniquely identify this request.
OrderProductRequest.TransactionDetail.TransactionTimestamp
DateTimestamp, Optional
The date and time when this request was created. When the request is from an
intermediary, such as a workflow manager or service bus, this is the date and
time when the message was sent to the D&B function, i.e., the date and time
when the xml document was created by the requesting intermediary.
D&B Direct API Documentation Custom:OrderProduct (SOAP)
©Dun & Bradstreet, Inc. 2014 19
Name Characteristics
OrderProductRequest.TransactionDetail.SubmittingOfficeID
string, up to 64 chars, Optional
A number that identifies the system or the software application from where this
request originated. / A number used to uniquely identfy the D&B business
segment or delivery channel from where this request originated.
End: OrderProductRequest.TransactionDetail
/Aggregate
OrderProductRequest.OrderProductRequestDetail
Aggregate, Optional
Records data relating to requests for a product. This may include such details as
the product required, the subject about which the product should be produced,
the content of the product.
OrderProductRequest.OrderProductRequestDetail.InquiryDetail
Aggregate, Required
Records data that allows the customer to specify identifying information about
the subject being inquired, e.g., the DUNS Number, the address, the telephone
number.
OrderProductRequest.OrderProductRequestDetail.InquiryDetail. DUNSNumber
string, up to 15 chars Pattern: {([0-9a-zA-Z]*)}, Optional
The D-U-N-S Number is D&B's identification number, which provides unique
identification of this organization, in accordance with the Data Universal
Numbering System (D-U-N-S).
OrderProductRequest.OrderProductRequestDetail.InquiryDetail. SubjectID
string, up to 15 chars, Optional
A number uniquely identifying the inquired subject within the D&B Worldwide
Network.
OrderProductRequest.OrderProductRequestDetail.InquiryDetail.CountryISOAlpha2Code
string, at least 2 chars up to 2 chars, Optional
The two-letter country code, defined in the ISO 3166-1 scheme published by
International Organization for Standardization (ISO)identifying the country of the
inquired subject.
OrderProductRequest.OrderProductRequestDetail.InquiryDetail.PrincipalIdentificationNumberDetail
Aggregate, Optional (Infinite)
An entry loop which can repeat multiple times to allow the recording of several
different identifiers issued by organizations to uniquely identify the principal. The
issuing organization may be a Registration Authority, Government Department
or Commercial Enterprise, e.g., the Social Security Administration department.
D&B Direct API Documentation Request Parameters
©Dun & Bradstreet, Inc. 2014 20
Name Characteristics
OrderProductRequest.OrderProductRequestDetail.InquiryDetail.PrincipalIdentificationNumberDetail@DNBCodeValue
Attribute
OrderProductRequest.OrderProductRequestDetail.InquiryDetail.PrincipalIdentificationNumberDetail@DNBCodeTableNumber
Attribute
OrderProductRequest.OrderProductRequestDetail.InquiryDetail.PrincipalIdentificationNumberDetail@TypeText
Attribute
OrderProductRequest.OrderProductRequestDetail.InquiryDetail.PrincipalIdentificationNumberDetail.PrincipalIdentificationNumber
string, Optional
A number assigned by an external body or by D&B which either uniquely
identifies or helps to identify an individual.
End: OrderProductRequest.OrderProductRequestDetail.InquiryDetail.PrincipalIdentificationNumberDetail
/Aggregate
End: OrderProductRequest.OrderProductRequestDetail.InquiryDetail
/Aggregate
OrderProductRequest.OrderProductRequestDetail.ProductSpecification
Aggregate, Required
Records data that allows the customer to specify the details of the requested
product. This may include details such as the identifier of the product, the
language in which the product needs to be rendered, the format in which the
product needs to be rendered.
OrderProductRequest.OrderProductRequestDetail.ProductSpecification. DNBProductID
string, Optional
An alphanumeric string that uniquely identifies the product being requested.
OrderProductRequest.OrderProductRequestDetail.ProductSpecification.LanguagePreferenceCode
integer, up to 7 digits, Optional
A D&B code value that defines the language in which the customer wants this
product to be rendered.
D&B Direct API Documentation Request Parameters
©Dun & Bradstreet, Inc. 2014 21
Name Characteristics
OrderProductRequest.OrderProductRequestDetail.ProductSpecification.CharacterSetPreferenceCode
integer, up to 7 digits, Optional
A D&B code value denoting the set of graphic symbols (e.g., alphabet letter,
pictograph) in which the product is to be rendered, e.g., Unicode.
OrderProductRequest.OrderProductRequestDetail.ProductSpecification.ProductFormatPreferenceCode
integer, up to 7 digits, Optional
OrderProductRequest.OrderProductRequestDetail.ProductSpecification.TradeUpIndicator
boolean, Optional
When 'true' indicates that the customer has requested that D&B return the
data for the Headquarters when the requested organization is a Branch. When
'false' indicates that the customer has not requested that D&B return the data
for the Headquarters when the requested organization is a Branch; however as
this is the assumed condition there is no requirement to create this tag to
represent this fact. Note: There are D&B WorldWide Network operations where
the Headquarters information will be returned automatically, regardless of the
customer request.
OrderProductRequest.OrderProductRequestDetail.ProductSpecification.OrderReasonCode
integer, up to 7 digits, Optional
Possible values: 6332 [Credit Decision]; 6333 [Assessment of credit solvency for
intended business connection]; 6334 [Assessment of credit solvency for ongoing
business connection]; 6335 [Debt Collection]; 6336 [Commercial Credit
Insurance]; 6337 [Insurance Contract]; 6338 [Leasing Agreement]; 6339 [Rental
Agreement]
End: OrderProductRequest.OrderProductRequestDetail.ProductSpecification
/Aggregate
OrderProductRequest.OrderProductRequestDetail.ArchiveDetail
Aggregate, Optional
OrderProductRequest.OrderProductRequestDetail.ArchiveDetail.ArchiveProductOptOutIndicator
boolean, Optional
When 'true' indicates that the product being ordered is not to be stored. When
'false' indicates that the product being ordered is to be stored; however as this is
the assumed condition there is no requirement to create this tag to represent
this fact.
D&B Direct API Documentation Request Parameters
©Dun & Bradstreet, Inc. 2014 22
Name Characteristics
OrderProductRequest.OrderProductRequestDetail.ArchiveDetail.ExtendArchivePeriodIndicator
boolean, Optional
When 'true' the duration to archive the data is to be extended. Note: There is an
additional cost for extending the archival period of the data purchased. When
'false' the duration to archive the data is not to be extended.
OrderProductRequest.OrderProductRequestDetail.ArchiveDetail.PortfolioAssetContainerID
long, Optional
A number used to uniquely identify the location where this product is to be
stored.
End: OrderProductRequest.OrderProductRequestDetail.ArchiveDetail
/Aggregate
OrderProductRequest.OrderProductRequestDetail.InquiryReferenceDetail
Aggregate, Optional
Records data that allows the customer to specify information to be linked to the
request in order to support subsequent order reconciliation.
OrderProductRequest.OrderProductRequestDetail.InquiryReferenceDetail.CustomerReferenceText
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 order reconciliation.
OrderProductRequest.OrderProductRequestDetail.InquiryReferenceDetail.CustomerBillingEndorsementText
string, at least 1 chars, up to 240 chars, Optional
Text that is filled in by customer and commonly contains requesting individual or
department name, or customer's own account/reference number and/or name
for the case on which the product was provided.This text is a reference used
during the billing process.
End: OrderProductRequest.OrderProductRequestDetail.InquiryReferenceDetail
/Aggregate
End: OrderProductRequest.OrderProductRequestDetail
/Aggregate
End: OrderProductRequest /Aggregate
Testing / Sandbox
This operation will return results in the D&B Direct sandbox (test) environment only when a test D-U-N-SNumber is provided in the request parameters.
D&B Direct API Documentation Testing / Sandbox
©Dun & Bradstreet, Inc. 2014 23
Data Field Response
The following is a list of the possible data fields returned by this operation in the XML response. The specificdata fields pre-configured for each custom data product will located in the response package as noted.
Name Characteristics
OrderProductResponse Aggregate
OrderProductResponse@ServiceVersionNumber
Attribute
OrderProductResponse.TransactionDetail
Aggregate, Required
Records information necessary to process a particular request. Examples of a
request is the ordering of a product.
OrderProductResponse.TransactionDetail.ApplicationTransactionID
string up to 64 chars., Optional
A number assigned by the calling application to uniquely identify this request.
OrderProductResponse.TransactionDetail.ServiceTransactionID
string up to 64 chars., Required
A number assigned by the D&B service to uniquely identify this transaction.
OrderProductResponse.TransactionDetail.TransactionTimestamp
DateTimestamp, Required
The date and time when this request was submitted or the date and time when
the requesting intermediary, such as a workflow manager or service bus, sent
the message to the D&B function, i.e., the date and time when the xml
document was created by the requesting intermediary.
End: OrderProductResponse.TransactionDetail
/Aggregate
OrderProductResponse.TransactionResult
Aggregate, Required
An aggregate that can repeat multiple times to record the different outcomes of
the transaction.
OrderProductResponse.TransactionResult. SeverityText
string up to 16 chars., Required
Text that records the criticality of the outcome, e.g., Information, Warning, Error,
Fatal.
OrderProductResponse.TransactionResult. ResultID
string up to 32 chars., Required
An alphanumeric string that uniquely identifies the outcome of the transaction.
OrderProductResponse.TransactionResult. ResultText
string up to 512 chars., Optional
Text that explains the outcome of the transaction.
D&B Direct API Documentation Data Field Response
©Dun & Bradstreet, Inc. 2014 24
Name Characteristics
OrderProductResponse.TransactionResult. ResultMessage
Aggregate, Optional (Infinite)
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 transaction. If the status implies that there is a
problem this may also provide guidance to the user on how to address it.
OrderProductResponse.TransactionResult. ResultMessage.ResultDescription
string up to 512 chars., Required
Text that describes the additional information regarding the outcome of the
transaction.
End: OrderProductResponse.TransactionResult. ResultMessage
/Aggregate
End: OrderProductResponse.TransactionResult
/Aggregate
OrderProductResponse.OrderProductResponseDetail
Aggregate, Optional
Records the data being returned to the customer as a result of a product request.
OrderProductResponse.OrderProductResponseDetail.InquiryDetail
Aggregate, Required
Records data that allows the customer to specify identifying information about
the subject being inquired, e.g., the DUNS Number, the address, the telephone
number.
OrderProductResponse.OrderProductResponseDetail.InquiryDetail. DUNSNumber
string up to 15 chars. Pattern: {([0-9a-zA-Z]*)}., Optional
The D&B's identification number, which provides unique identification of the
inquired organization, in accordance with the Data Universal Numbering System
(D-U-N-S).
OrderProductResponse.OrderProductResponseDetail.InquiryDetail. SubjectID
string up to 15 chars., Optional
A number uniquely identifying the inquired subject within the D&B Worldwide
Network.
OrderProductResponse.OrderProductResponseDetail.InquiryDetail.CountryISOAlpha2Code
string at least 2 chars. up to 2 chars., Optional
The two-letter country code, defined in the ISO 3166-1 scheme published by
International Organization for Standardization (ISO)identifying the country of the
inquired subject.
D&B Direct API Documentation Data Field Response
©Dun & Bradstreet, Inc. 2014 25
Name Characteristics
OrderProductResponse.OrderProductResponseDetail.InquiryDetail.PrincipalIdentificationNumberDetail
Aggregate, Optional (Infinite)
An entry loop which can repeat multiple times to allow the recording of several
different identifiers issued by organizations to uniquely identify the principal. The
issuing organization may be a Registration Authority, Government Department
or Commercial Enterprise, e.g., the Social Security Administration department.
OrderProductResponse.OrderProductResponseDetail.InquiryDetail.PrincipalIdentificationNumberDetail@DNBCodeValue
Attribute
OrderProductResponse.OrderProductResponseDetail.InquiryDetail.PrincipalIdentificationNumberDetail@DNBCodeTableNumber
Attribute
OrderProductResponse.OrderProductResponseDetail.InquiryDetail.PrincipalIdentificationNumberDetail@TypeText
Attribute
OrderProductResponse.OrderProductResponseDetail.InquiryDetail.PrincipalIdentificationNumberDetail.PrincipalIdentificationNumber
string, Optional
A number assigned by an external body or by D&B which either uniquely
identifies or helps to identify an individual.
End: OrderProductResponse.OrderProductResponseDetail.InquiryDetail.PrincipalIdentificationNumberDetail
/Aggregate
End: OrderProductResponse.OrderProductResponseDetail.InquiryDetail
/Aggregate
OrderProductResponse.OrderProductResponseDetail.Product
Aggregate, Required
Records data about the product ordered by the customer and data about the
organization on which the customer has placed this order.
OrderProductResponse.OrderProductResponseDetail.Product. DNBProductID
string up to 64 chars., Optional
An alphanumeric string that uniquely identifies this product.
D&B Direct API Documentation Data Field Response
©Dun & Bradstreet, Inc. 2014 26
Name Characteristics
OrderProductResponse.OrderProductResponseDetail.Product. LanguageCode
integer up to 7 digits., Optional
A D&B code value that defines the language in which the requested product is
fulfilled.
OrderProductResponse.OrderProductResponseDetail.Product. Organization
Aggregate, Required
Records data about an organization, a legal or commercial entity established to
provide products and/or services in the marketplace or to the community.
Contents of "Organization PCMAggregate
Contents of "Organization PCM Aggregate
Possible values: Contents of "Organization PCM Aggregate
END: OrderProductResponse.OrderProductResponseDetail.Product. Organization
/Aggregate
OrderProductResponse.OrderProductResponseDetail.Product. ArchiveDetail
Aggregate, Optional
Records data about the archival details of the product requested.
OrderProductResponse.OrderProductResponseDetail.Product. ArchiveDetail.PortfolioAssetID
PortfolioAssetIDType, Optional
A number used to uniquely identify this product in the location where it is stored.
OrderProductResponse.OrderProductResponseDetail.Product. ArchiveDetail.PortfolioAssetContainerID
long, Optional
A number used to uniquely identify the location where this product is stored.
End: OrderProductResponse.OrderProductResponseDetail.Product. ArchiveDetail
/Aggregate
OrderProductResponse.OrderProductResponseDetail.Product. CopyrightNoticeText
string up to 128 chars., Optional
Text that specifies the underlying claim to copyright ownership of this product.
End: OrderProductResponse.OrderProductResponseDetail.Product
/Aggregate
OrderProductResponse.OrderProductResponseDetail.InquiryReferenceDetail
Aggregate, Optional
Records data that allows the customer to specify information to be linked to the
request in order to support subsequent order reconciliation.
OrderProductResponse.OrderProductResponseDetail.InquiryReferenceDetail.CustomerReferenceText
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 order reconciliation.
D&B Direct API Documentation Data Field Response
©Dun & Bradstreet, Inc. 2014 27
Name Characteristics
OrderProductResponse.OrderProductResponseDetail.InquiryReferenceDetail.CustomerBillingEndorsementText
string at least 1 chars. up to 240 chars., Optional
Text that is filled in by customer and commonly contains requesting individual or
department name, or customer's own account/reference number and/or name
for the case on which the product was provided.This text is a reference used
during the billing process.
End: OrderProductResponse.OrderProductResponseDetail.InquiryReferenceDetail
/Aggregate
End: OrderProductResponse.OrderProductResponseDetail
/Aggregate
End: OrderProductResponse /Aggregate
Lists of possible values (when present) are subject to change. Additional values not presented in this documentation may be delivered
in the response and should be anticipated in any implementation.
Abbreviated Territory Names
When present, the Territory Abbreviated Name field will contain local abbreviations, which may be based onstandard designations. For companies domiciled in the United States or Canada, this field will contain thesecond component of ISO 3166-2 codes. For example, the ISO 3166-2:US code for New Jersey is "US-NJ" andthe value "NJ" will be delivered in this field. Similarly, the ISO 3166-2:CA code for Ontario is "CA-ON" and thevalue "ON" will be delivered in this field.
Language/Character Sets
The text contained within D&B Direct 2.0 data layers is returned in English. Several reports, including theD&B Business Information Report (BIR), provide additional language options. Data layers are encoded usingthe ISO 8859-1 character set standard (sometimes referred to as Latin-1), EXCEPT when the organization isdomiciled in the Czech Republic (CZ), Hungary (HU), Poland (PL) or Slovakia (SK). Data from these markets iscurrently encoded using the ISO 8859-2 character set standard.
Response Codes
Successful service requests will return a CM000 response code. Otherwise, one of the D&B Direct standardresponse codes will be returned.
This operation may return the following response codes: CM001-CM005, CM007-CM012, CM014, CM017,CM018, PD001, PD003, PD005, PD006, PD015, PD016, and SC001-SC012.
D&B Direct API Documentation Abbreviated Territory Names
©Dun & Bradstreet, Inc. 2014 28
Product (Data Layer) Details
Title / Overview Link Product Code Countries
D&B Direct 2.0 - Custom Product CST_PRD_1 to CST_PRD_6 varies
Samples (Download)
Request and response samples are available for this D&B Direct web services. The samples may cover avariety of scenarios (when applicable) and are designed for use in the test environment.
Custom Product Service
Samples http://developer.dnb.com/docs/2.0/custom/2.0/DnB-Custom.zip
Related Topics
{productservice}:RetrieveProduct (SOAP)
D&B Direct API Documentation Product (Data Layer) Details
©Dun & Bradstreet, Inc. 2014 29
Authentication ProcessBefore D&B Direct API services can be invoked, the credentials must be activated. Instructions and a link foractivating username/password combinations will be included in an email sent upon completion of theregistration process. If you do not receive an email, or unable to locate it, please contact the D&B supportteam for assistance (and specify if this a production, trial or sandbox related issue).
The system will generate a unique username for accounts created after December 6, 2013. Prior to that date,the customer-supplied email address was used as the username. No change is required for existing credentials.
Most of the D&B Direct products and features require contractual entitlement prior to production (and trial)environment access. Please refer to the data layer entitlement page for more details.
SOAP Authentication
All D&B Direct API services require that a valid username and password be provided in the SOAP header witheach call to an operation. The 2.0 services do not require that an API key be supplied.
If the credentials are valid and the associated account is entitled to access the product or feature, the requestwill be processed. If the authentication process fails, an error response code will be returned. The securityrelated response codes are prefixed with "SC."
Sample Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:com="http://services.dnb.com/CompanyServiceV2.0">
<soapenv:Header><wsse:Security soapenv:mustUnderstand="0" xmlns:wsse="http://do
cs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-11"><wsse:Username>MyUsername</wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/
01/oasis-200401-wss-username-token-profile-1.0#PasswordText">MyPassword</wsse:Password>
</wsse:UsernameToken></wsse:Security>
</soapenv:Header><soapenv:Body>
<!--Request Body as per the service schema-->
D&B Direct API Documentation Authentication Process
©Dun & Bradstreet, Inc. 2014 30
</soapenv:Body></soapenv:Envelope>
Response - Invalid Credentials
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body><com:MatchResponse ServiceVersionNumber="4.0" xmlns:com="http:/
/services.dnb.com/CompanyServiceV2.0"><TransactionDetail>
<ApplicationTransactionID>Id-b118ae275255a7cf0cfb742e</ApplicationTransactionID>
<ServiceTransactionID>Id-b118ae275255a7cf0cfb742e</ServiceTransactionID>
<TransactionTimestamp>2013-10-09T15:00:31</TransactionTimestamp>
</TransactionDetail><TransactionResult>
<SeverityText>Error</SeverityText><ResultID>SC001</ResultID><ResultText>Your user credentials are invalid. Please con
tact your D&B Representative or your local Customer Service Center.</ResultText>
</TransactionResult></com:MatchResponse>
</soapenv:Body></soapenv:Envelope>
REST Authentication
Implementation of D&B Direct API services using REST methodology involves obtaining anAuthentication Token, that is then submitted with subsequent requests during a particular session (up to eighthours).
Secure access to D&B Direct services is managed through the use of an Authentication Token, which can beobtained by sending an HTTP POST request to Authentication Service URL, passing a valid username andpassword in the HTTP header. The 2.0 services do not require that an API key be supplied. If the usercredentials are valid, an Authentication Token (valid for eight hours) will be returned back in theAuthorization tag in the HTTP header of the response.
D&B Direct API Documentation REST Authentication
©Dun & Bradstreet, Inc. 2014 31
Once an Authentication Token is obtained, it should be embedded in the HTTP header of all subsequentrequests. If the Authentication Token is valid and the user is entitled to access the product or feature beingrequested, the service will be processed and requested information returned as a JSON object. If theAuthentication Token is invalid, an error code will be returned in the JSON response.
Note: The D&B Direct REST implementation uses the BadgerFish approach for JSON with some minorvariations.
Sample Request - Get New Token
POST https://maxcvservices.dnb.com/rest/Authenticationx-dnb-user: MyUsernamex-dnb-pwd: MyPassword
A {version} parameter is not required when initiating a request to the Authentication service.
Response - Success
HTTP/1.1 200 OKDate: Wed, 09 Oct 2013 18:47:22 GMTAuthorization: <MyToken>x-dnb-user: MyUsernamex-dnb-pwd: MyPassword
Response - Failed
HTTP/1.1 401 ERRORDate: Wed, 09 Oct 2013 18:51:11 GMTAuthorization: INVALID CREDENTIALSx-dnb-user: MyUsernamex-dnb-pwd: MyPassword
Sample Request - Invoke Operation with Token
GET https://maxcvservices.dnb.com/V4.0/organizations?CountryISOAlpha2Code=US&SubjectName=GORMAN%20MANUFACTURING&match=true&MatchTypeText=Advanced&TerritoryName=CAAuthorization: <MyToken>
Response - Expired Authentication Token
HTTP/1.1 401 UNAUTHORIZEDDate: Thu, 10 Oct 2013 14:55:19 GMT
D&B Direct API Documentation REST Authentication
©Dun & Bradstreet, Inc. 2014 32
Authorization: <MyToken>Content-Type: application/jsonContent-Encoding: gzip
{"MatchResponse": {"TransactionDetail": {
"ApplicationTransactionID": "REST","ServiceTransactionID": "Id-c04bbdff5256bfd70a7b742e","TransactionTimestamp": "2013-10-10T10:55:19"
},"TransactionResult": {
"SeverityText": "Error","ResultID": "SC001","ResultText": "Your user credentials are invalid. Please contact
your D&B Representative or your local Customer Service Center."}
}}
D&B Direct API Documentation REST Authentication
©Dun & Bradstreet, Inc. 2014 33
Obtaining CredentialsAccess to the D&B Direct web services are secured by a username and password combination. D&B will issueyour organization a production username upon completion of the contract establishment process. Thisusername will be sent to the email address designated on the contract, along with instructions for setting upthe password. This process will also be followed for production trial requests.
D&B offers a non-billable environment (commonly referred to as the sandbox) for testing the D&B Direct webservices. Developers may establish, via a self-service interface, sandbox user id and password combinations.The production credentials assigned to your organization may NOT be used in the sandbox environment toauthenticate web services, and vice-versa.
Before D&B Direct API services can be invoked, the credentials must be activated. Instructions and a link foractivating username/password combinations will be included in an email sent upon completion of theregistration process. If you do not receive an email, or unable to locate it, please contact the D&B supportteam for assistance (and specify if this a production, trial or sandbox related issue).
The system will generate a unique username for accounts created after December 6, 2013. Prior to that date,the customer-supplied email address was used as the username. No change is required for existing credentials.
Most of the D&B Direct products and features require contractual entitlement prior to production (and trial)environment access. Please refer to the data layer entitlement page for more details.
D&B Direct API Documentation Obtaining Credentials
©Dun & Bradstreet, Inc. 2014 34
Data Layer EntitlementD&B Direct 2.0 services are provisioned to customers at the data layer, which, for some of the features, mightnot be intuitive. This page is intended to help developers clearly understand what services and operations theyare entitled to use.
Components Requiring Entitlement
Data Layer: D&B Direct 2.0 - Custom Product 1 to 6Service: Custom Product ServiceOperation: OrderProduct() + CST_PRD_1 to CST_PRD_6Product: Custom Product Selection
Components Not Requiring Entitlement
These items are available to customers who have one or more entitled data layers.
D&B Direct API Documentation Data Layer Entitlement
©Dun & Bradstreet, Inc. 2014 35
Country CodesMany of the D&B Direct web services expect to receive a country code for the company specified by the D-U-N-S Number being requested. This input parameter is case-sensitive and must be supplied in upper case.On some requests, this parameter is optional; however, D&B recommends that it be provided to reduce theresponse time of the service(s) -- including products limited to results for US companies.
D&B Direct services utilize the two-letter country code as defined by the International Organization forStandardization (ISO) in their ISO 3166-1 specification. For a list of actual country codes supported for aspecific data layer, please refer to the Country Availability tab contained in the downloadable "Extras" file forthe respective Service.
Code Substitutions
Data for the following countries is stored under the alternate country code specified.
Country Name Alternate Instructions
ABU DHABI Use the code of United Arab Emirates (AE)
ADMIRALTY ISLANDS Use the code of Papua New Guinea (PG)
AJMAN Use the code of United Arab Emirates (AE)
AL AIN Use the code of United Arab Emirates (AE)
ASCENSION ISLAND Use the code SH (Saint Helena, Ascension and Tristan da Cunha)
Cocos (Keeling) Islands Use the code AU (Australia)
DUBAI Use the code of United Arab Emirates (AE)
FUJAIRAH Use the code of United Arab Emirates (AE)
MIDWAY ISLANDS Use the code of US
RAS AL KHAIMAH Use the code of United Arab Emirates (AE)
SHARJAH Use the code of United Arab Emirates (AE)
SOUTH SANDWICH ISLANDS Use the code GS (South Georgia and the South Sandwich Islands)
South Sudan Use the code of Sudan (SD)
TURKISH CYPRUS Use the code of Cyprus (Match is not supported)
UMM-AL-QUWAIN Use the code of United Arab Emirates (AE)
While some territories of the United States (e.g. Puerto Rico) have been assigned ISO country codes, theinformation on organizations from those areas will be located under the US country code.
Data Not Available
Data for the following countries is not currently available through the D&B Direct 2.0 API.
D&B Direct API Documentation Country Codes
©Dun & Bradstreet, Inc. 2014 36
Country Name ISO Code
Antarctica AQ
Åland Islands AX
Saint Barthélemy BL
Bonaire, Saint Eustatius and Saba BQ
Bouvet Island BV
CAROLINE ISLANDS ??
Cuba CU
Curaçao CW
Western Sahara EH
Micronesia, Federated States of FM
Guernsey GG
Heard Island and McDonald Islands HM
Isle of Man IM
British Indian Ocean Territory IO
Jersey JE
Korea, Democratic People's Republic of KP
Saint Martin (French part) MF
Mongolia MN
Niue NU
Pitcairn PN
Palestinian Territory, Occupied PS
Palau PW
Svalbard and Jan Mayen SJ
Sint Maarten (Dutch part) SX
French Southern Territories TF
Wallis and Futuna WF
Wake Island ??
Mayotte YT
Please contact your local D&B Customer Service department/representative for more details; or to place aninquiry for a specific organization.
D&B Direct API Documentation Country Codes
©Dun & Bradstreet, Inc. 2014 37
Response CodesWhenever a D&B Direct web service request is unsuccessful, one of the following response codes will bereturned.
Code Description HTTPStatus*
CM000 Success 200
CM001 The given request is invalid. 400
CM002 The format of this request is invalid. 400
CM003 Missing information in the request. 400
CM004 Internal D&B system error. 500
CM005 D&B System temporarily unavailable. 503
CM006 D&B System busy. 503
CM007 Your request cannot be fulfilled for the given criteria. 404
CM008 No match found for the requested Duns number. 404
CM009 Reason Code required for Germany. 400
CM010 Partial Success. 200
CM011 Invalid Country Code provided in the request. 400
CM012 Invalid Duns number provided in the request. 400
CM013 Invalid Subject ID provided in the request. 400
CM014 Invalid Product Code provided in the request. 400
CM016 Invalid Territory provided in the request. 400
CM017 Duns number is missing in the request. 400
CM018 No candidates resulted for the given input criteria. 404
CM022 Only a Subset of request parameters were used for processing the request. 200
CM023 Duplicate record cannot be created. 400
CM026 Request accepted. Processing pending. 200
CP001 No Match for the given input criteria. 404
CP002 No candidates resulted in the Extended Search. 404
CP003 No Match for given Telephone Number. 404
CP004 No Match for given Organization Identifier. 404
CP005 Insufficient Information to determine Fraud Score. 400
PD001 Requested product not available due to insufficient data. 404
PD002 Requested subject is promised later. Preliminary report returned. 200
PD003 Requested product not available - subject is on Stop Distribution. 404
D&B Direct API Documentation Response Codes
©Dun & Bradstreet, Inc. 2014 38
Code Description HTTPStatus*
PD004 Requested product not available due to subject information is too old. 404
PD005 Requested Product not available. 404
PD006 Subject is foreign branch, therefore trade-up to HQ is not available. 404
PD007 Family Tree does not exist for requested subject. 404
PD008 Success. Returned truncated family tree, as family tree member countexceeds maximum limit for requested subject.
200
PD009 Required scoring elements missing - a Commercial or Blended Small Businessreport is not available. You may proceed with a Principal only request.
200
PD010 Requested Product not available as address is undeliverable. 200
PD011 Requested Product not available as address is undeliverable. 404
PD012 Requested Product not available on Self request. 404
PD013 Requested Product is not available currently. Product will be delivered to thecustomer at a later point of time via offline delivery channels (Email/FAX/FTPetc).
404
PD014 Requested data is not available or partially available due to data integrityerrors.
404
PD015 Trade-up to HQ is not available. Therefore delivering the data for branchorganization.
200
PD016 Requested Product is not available since the requested DUNS is transferred toa new DUNS.
200
SC001 Your user credentials are invalid. 401
SC002 Your user credentials are not eligible for this request. 401
SC003 Your user credentials have expired. 401
SC004 Your Subscriber number has expired. 401
SC005 You have reached maximum limit permitted as per the contract. 401
SC006 Transaction not processed as the permitted concurrency limit was exceeded. 401
SC007 Subscriber validation failed. 401
SC008 Your account has been locked out due to repeated attempts to login with anincorrect User ID/Password.
401
SC009 Invalid Sign On Token in the request. 401
SC010 The User ID you provided doesn’t exist in the system. n/a
SC011 The User ID you provided already exist in the system n/a
SC012 Request not processed as user activation key is invalid or expired. n/a
SC014 Your user credentials are not eligible for this request since you are in trialperiod.
401
BC001 Partial Success. One or more records in the input file were not processed. 200
D&B Direct API Documentation Response Codes
©Dun & Bradstreet, Inc. 2014 39
Code Description HTTPStatus*
BC002 Batch request is not processed since input file is not available in the specifiedlocation.
400
BC003 Batch request is not processed since the content of the input file is not in theexpected format.
400
BC004 Batch request is not processed since the count of the records specified in therequest do not match the exact count of records in the input file.
400
BC005 Intermediate Success 200
BC006 Batch request is not processed 400
BC007 Batch Execution in progress n/a
BC008 Batch Execution not yet started n/a
BC009 Batch not processed as the input file contains more records than thepermitted limit.
400
BC010 Batch files no longer available after retention period. 200
BC011 Invalid Batch Process Id provided in the request. 400
MN001 Invalid Monitoring Profile ID provided in the request. 400
MN002 Invalid Notification Profile ID provided in the request. 400
MN003 Product not registered for Level 2 Monitoring 400
MN004 Cannot delete Monitoring Profile - registrations exist 400
MN005 Cannot delete Notification Profile - registrations exist. 400
*This column displays the corresponding HTTP status code that will be returned for REST API calls.
D&B Direct API Documentation Response Codes
©Dun & Bradstreet, Inc. 2014 40
Sandbox AccessD&B Direct provides a test environment (referred to as the sandbox) that requires a separate set of credentials.Service requests made with sandbox credentials should be issued using the same endpoints (and in the case ofSOAP, using the same WSDL file).
When conducting testing in the production environment during a trial period, product requests will be limitedto the local market of the customer.
Some D&B Direct products and features may behave differently in the sandbox environment. Any limitationsor restrictions will be specified on the operation page for each interface.
Test Parameter Values
The following suggested parameters may be used for test environment (sandbox) requests to retrievesuccessful responses.
Company Reports
Country Reports
Static Responses
Some operations currently return a static set of results, regardless of the request parameters, in the testenvironment.
Company Service
Match, GetCleanseMatch, SearchByFilingName, SearchByFilingNumber, and CleanseAndStandardize will returna static response in the Sandbox environment.
Entity List Service
FindCompany, FindContact, FindCompetitor, and FindIndustry will return a static response in the Sandboxenvironment.
D&B Direct API Documentation Sandbox Access
©Dun & Bradstreet, Inc. 2014 41
{data products}:RetrieveProduct (REST)This operation -- included in all data and report product services (listed below)-- provides access to the productrequest archive. Assets may also be retrieved by using the Portfolio:RetrievePortfolioAsset (REST) operation.
Service Request Response*
Custom Product Service RetrieveProduct() same as OrderProduct()
*The response data field names will be prefixed with "RetrieveProductResponse.RetrieveProductResponseDetail" instead
of "OrderProductResponse.OrderProductResponseDetail".
Request Parameters
The following parameters are accepted by this operation; however, the requirements for a specific requestmay differ based the product being requested.
Name Characteristics
ApplicationTransactionID string up to 64 chars., Optional
A number assigned by the
calling application to uniquely
identify this request.
TransactionTimestamp DateTimestamp, Optional
The date and time when this
request was created. When
the request is from an
intermediary, such as a
workflow manager or service
bus, this is the date and time
when the message was sent to
the D&B function, i.e., the date
and time when the xml
document was created by the
requesting intermediary.
D&B Direct API Documentation {data products}:RetrieveProduct (REST)
©Dun & Bradstreet, Inc. 2014 42
Name Characteristics
SubmittingOfficeID string up to 64 chars., Optional
A number that identifies the
system or the software
application from where this
request originated. / A number
used to uniquely identfy the
D&B business segment or
delivery channel from where
this request originated.
{assetID} long, Required
Response Data Fields
Refer to the respective OrderProduct operation for each service. For example, a request fromAssessment:RetrieveProduct() will return the same response as Assessment:OrderProduct(). The responseitems, however, will be prefixed with "RetrieveProductResponse.RetrieveProductResponseDetail" insteadof "OrderProductResponse.OrderProductResponseDetail".
Language/Character Sets
The text contained within D&B Direct 2.0 data layers is returned in English. Several reports, including theD&B Business Information Report (BIR), provide additional language options. Data layers are encoded usingthe ISO 8859-1 character set standard (sometimes referred to as Latin-1), EXCEPT when the organization isdomiciled in the Czech Republic (CZ), Hungary (HU), Poland (PL) or Slovakia (SK). Data from these markets iscurrently encoded using the ISO 8859-2 character set standard.
Response Codes
Successful service requests will return a CM000 response code. Otherwise, one of the D&B Direct standardresponse codes will be returned.
This operation may return the following response codes: CM001, CM002, CM003, CM004, CM005, CM006,PT001, and SC001-SC009.
Operation-specific supplemental response code explanations:
PT001 No Portfolio asset not found for given portfolio asset identifier or investigation tracking ID or assetremoved from archive.
D&B Direct API Documentation Response Data Fields
©Dun & Bradstreet, Inc. 2014 43
SOAP Interface
This operation is also available using the SOAP architecture. Refer to {data products}:RetrieveProduct (SOAP)for details.
D&B Direct API Documentation SOAP Interface
©Dun & Bradstreet, Inc. 2014 44
{data products}:RetrieveProduct (SOAP)This operation -- included in all data and report product services (listed below)-- provides access to the productrequest archive. Assets may also be retrieved by using the Portfolio:RetrievePortfolioAsset (REST) operation.
Service Request Response*
Custom Product Service RetrieveProduct() same as OrderProduct()
*The response data field names will be prefixed with "RetrieveProductResponse.RetrieveProductResponseDetail" instead
of "OrderProductResponse.OrderProductResponseDetail".
Request Parameters
The following parameters are accepted by this operation; however, the requirements for a specific requestmay differ based the product being requested.
Name Characteristics
RetrieveProductRequest Aggregate
RetrieveProductRequest@ServiceVersionNumber Attribute
RetrieveProductRequest. TransactionDetail Aggregate, Optional
Records information necessary to process this request.
RetrieveProductRequest. TransactionDetail.ApplicationTransactionID
string up to 64 chars., Optional
A number assigned by the calling application to uniquely identify this
request.
RetrieveProductRequest. TransactionDetail.TransactionTimestamp
DateTimestamp, Optional
The date and time when this request was created. When the
request is from an intermediary, such as a workflow manager or
service bus, this is the date and time when the message was sent to
the D&B function, i.e., the date and time when the xml document
was created by the requesting intermediary.
RetrieveProductRequest. TransactionDetail.SubmittingOfficeID
string up to 64 chars., Optional
A number that identifies the system or the software application
from where this request originated. / A number used to uniquely
identfy the D&B business segment or delivery channel from where
this request originated.
END: RetrieveProductRequest. TransactionDetail /Aggregate
D&B Direct API Documentation {data products}:RetrieveProduct (SOAP)
©Dun & Bradstreet, Inc. 2014 45
Name Characteristics
RetrieveProductRequest.RetrieveProductRequestDetail
Aggregate, Required
RetrieveProductRequest.RetrieveProductRequestDetail. ArchiveDetail
Aggregate, Required
RetrieveProductRequest.RetrieveProductRequestDetail. ArchiveDetail.PortfolioAssetID
long, Required
END: RetrieveProductRequest.RetrieveProductRequestDetail. ArchiveDetail
/Aggregate
END: RetrieveProductRequest.RetrieveProductRequestDetail
/Aggregate
END: RetrieveProductRequest /Aggregate
Response Data Fields
Refer to the respective OrderProduct operation for each service. For example, a request fromAssessment:RetrieveProduct() will return the same response as Assessment:OrderProduct(). The responseitems, however, will be prefixed with "RetrieveProductResponse.RetrieveProductResponseDetail" insteadof "OrderProductResponse.OrderProductResponseDetail".
Language/Character Sets
The text contained within D&B Direct 2.0 data layers is returned in English. Several reports, including theD&B Business Information Report (BIR), provide additional language options. Data layers are encoded usingthe ISO 8859-1 character set standard (sometimes referred to as Latin-1), EXCEPT when the organization isdomiciled in the Czech Republic (CZ), Hungary (HU), Poland (PL) or Slovakia (SK). Data from these markets iscurrently encoded using the ISO 8859-2 character set standard.
Response Codes
Successful service requests will return a CM000 response code. Otherwise, one of the D&B Direct standardresponse codes will be returned.
This operation may return the following response codes: CM001, CM002, CM003, CM004, CM005, CM006,PT001, and SC001-SC009.
Operation-specific supplemental response code explanations:
PT001 No Portfolio asset not found for given portfolio asset identifier or investigation tracking ID or assetremoved from archive.
D&B Direct API Documentation Response Data Fields
©Dun & Bradstreet, Inc. 2014 46
REST Interface
This operation is also available using the REST architecture. Refer to {data products}:RetrieveProduct (REST) fordetails.
D&B Direct API Documentation REST Interface
©Dun & Bradstreet, Inc. 2014 47
BadgerFish (REST)BadgerFish is a convention for translating an XML document into a JSON object. D&B Direct JSON responsesfollow this convention with a few minor variations. Exception: The responses supplied by the DataExchange Service follow the convention used by the respective business partner.
l Attributes will always be represented by prefixing with “@”. (see Example 2)l If an element is repeatable, that element will be always returned as an Array of objects in the JSON
response. (see Example 7)o If a repeatable element is not repeating in a specific JSON response, even then that element will
be returned as an Array having a single object. (see Example 9)l Element content will be represented with “$” if it has attributes (see Example 2)
o Consider a scenario where an element has an attribute as per the definition, however theattribute is not returned in a specific JSON response. Even then, the element content will berepresented as “$” in the JSON. (see Example 4)
l String values will be returned within double quotes. (see Example 14)l Numeric and Boolean values will not be returned within double quotes. (see Example 12 and Example
13)
Examples
# Scenario XML Instance JSON Instance
1 Element having noattribute
<DUNSNumber>804735132 </DUNSNumber> "DUNSNumber": "804735132"
2 Element havingAttribute
<FamilyTreeMemberRoleTextDNBCodeValue="12773">Parent</FamilyTreeMemberRoleText>
"FamilyTreeMemberRoleText": { "@DNBCodeValue": 12773, "$": "Parent" }
3 Aggregate havingattribute
<OrganizationIdentificationNumberDetailTypeText="Federal Taxpayer IdentificationNumber (US)" DNBCodeValue="6863"><OrganizationIdentificationNumber>12345</OrganizationIdentificationNumber></OrganizationIdentificationNumberDetail>
"OrganizationIdentificationNumberDetail":{ "@TypeText": "Federal TaxpayerIdentification Number (US)","@DNBCodeValue": 6863,"OrganizationIdentificationNumber":"12345" }
4 Element havingAttribute as perdefinition, howeverattribute is notreturned for aspecific JSONinstance
<OrganizationName>Gorman ManufacturingCompany, Inc. </OrganizationName>
"OrganizationName": { "$": "GormanManufacturing Company, Inc." }
D&B Direct API Documentation BadgerFish (REST)
©Dun & Bradstreet, Inc. 2014 48
# Scenario XML Instance JSON Instance
5 Aggregate havingAttribute as perdefinition, howeverattribute is notreturned for aspecific JSONinstance
<OrganizationIdentificationNumberDetail ><OrganizationIdentificationNumber>12345</OrganizationIdentificationNumber></OrganizationIdentificationNumberDetail>
"OrganizationIdentificationNumberDetail":{ "OrganizationIdentificationNumber":"12345" }
6 Non-RepeatingElement
<DUNSNumber>804735132 </DUNSNumber> "DUNSNumber": "804735132"
7 Repeating Element <SalesRevenueAmountCurrencyISOAlpha3Code="USD”>1000000</SalesRevenueAmount><SalesRevenueAmountCurrencyISOAlpha3Code="CAD”>1040000</SalesRevenueAmount>
"SalesRevenueAmount": [ { "@CurrencyISOAlpha3Code": "USD", "$":1000000 }, { "@CurrencyISOAlpha3Code":"CAD", "$": 1040000 } ]
8 Repeating Aggregate <FamilyTreeMemberRole><FamilyTreeMemberRoleTextDNBCodeValue="12773">Parent</FamilyTreeMemberRoleText></FamilyTreeMemberRole><FamilyTreeMemberRole><FamilyTreeMemberRoleTextDNBCodeValue="12775">Global Ultimate</FamilyTreeMemberRoleText></FamilyTreeMemberRole><FamilyTreeMemberRole><FamilyTreeMemberRoleTextDNBCodeValue="12774">Domestic Ultimate</FamilyTreeMemberRoleText></FamilyTreeMemberRole>
"FamilyTreeMemberRole": [ {"FamilyTreeMemberRoleText": { "@DNBCodeValue": 12773, "$": "Parent" }},{"FamilyTreeMemberRoleText": {
"@DNBCodeValue": 12775, "$": "GlobalUltimate" }},{"FamilyTreeMemberRoleText": { "@DNBCodeValue": 12774, "$": "DomesticUltimate" }} ]
9 Element isrepeatable as per thedefinition. Howeverit is not repeating ina specific JSONinstance.
<SalesRevenueAmountCurrencyISOAlpha3Code="USD”>1000000</SalesRevenueAmount>
"SalesRevenueAmount": [ { "@CurrencyISOAlpha3Code": "USD", "$":1000000 }]
10 Aggregate isrepeatable as per thedefinition. Howeverit is not repeating ina specific JSONinstance.
<FamilyTreeMemberRole><FamilyTreeMemberRoleTextDNBCodeValue="12773">Parent</FamilyTreeMemberRoleText></FamilyTreeMemberRole>
"FamilyTreeMemberRole": [ {"FamilyTreeMemberRoleText": { "@DNBCodeValue": 12773, "$": "Parent" }}]
11 Date Field <TransactionTimestamp>2013-07-11T11:08:48.067-04:00</TransactionTimestamp>
"TransactionTimestamp": "2013-07-11T11:10:39.110-04:00"
12 Boolean Field <StandaloneOrganizationIndicator>false</StandaloneOrganizationIndicator>
"StandaloneOrganizationIndicator": false
D&B Direct API Documentation Examples
©Dun & Bradstreet, Inc. 2014 49
# Scenario XML Instance JSON Instance
13 Numeric Field <RawScore>352</RawScore> "RawScore": 352
14 String Field <LineText>492 Koller Street</LineText> "LineText": "492 Koller Street"
D&B Direct API Documentation Examples
©Dun & Bradstreet, Inc. 2014 50
Dun & Bradstreet (D&B)
103 JFK Parkway
Short Hills, NJ 07078
www.dnb.com
©Dun & Bradstreet, Inc. 2014. All rights reserved.