Ordering Custom Products
| Product(s) | D&B Direct 2.0 |
| Product Code(s) | CST_PRD_1 to CST_PRD_6 |
| Level(s) | Standard |
| Monitoring Available | Yes |
| Interface | REST |
| Method | GET |
| Format(s) | JSON |
| Service | CustomProduct |
| {version} | 3.0 |
| 3.0 Released On | August 21, 2015 |
D&B Direct allows the creation of custom collections of data elements per customer account. Custom collections are configured by D&B Sales Associates, and then made available through API calls.
Update History
- October 22, 2021 (ALL SOAP & REST): Mapping update for Legal events indicators to use updated Scots Code.
- October 08, 2021 (ALL SOAP & REST): Defect fix to suppress principal information of non-English Principal name to avoid incomplete Principal and Management section in the response.
- August 18, 2017 (v3.1 SOAP & REST): Upgraded Custom Product service to version 3.1.
- August 18, 2017 (v3.0 SOAP & REST): Updated monitoring paths in response elements specification.
- July 15, 2016 (v3.0 SOAP & REST): Monitoring for GBO product has been enabled for the following countries; Austria, Belgium, Germany, Italy, Ireland, Luxembourg, Netherlands, Portugal, Spain, Switzerland, and United Kingdom.
- July 15, 2016 (v3.0 SOAP & REST): SR_GLB and SR_SLJ data layers released as part of D&B Direct 2.0 API.
- July 15, 2016 (v3.0 SOAP & REST): SMPL_OWNSHP, GBO and KYC data layers released as part of D&B Direct 2.0 API.
- July 15, 2016 (v3.0 SOAP & REST): CMP_VRF_ID and CMP_VRF_RPT data layers released as part of D&B Direct Onboard API.
- March 21, 2016, (v3.0 SOAP & REST): CountryGroupName, LastUpdateDate, CountryOfficialName, RegistrationIssuerName, RegistrationLocationName, TelecommunicationAddress, ActiveSanctionsIndicator, MatchedSubjectName, MatchedEntityTypeText, MatchKeywordText, MatchedIndicator, SanctionListName, SanctionsAuthorityWebPageAddress, ChildrenQuantity, ChildrenTypeText, GlobalUltimateFamilyTreeLinkageCount, and SubjectFamilyTreeLinkageCount are added.
- January 29, 2016 (v3.0 SOAP & REST): The element OperatingStatusFromDate is available for CST_PRD 1 to 6.
- December 11, 2015 (v3.0 SOAP & REST): United Nations Standard Products and Services Code is now available for CST_PRD 1 to 6; D-U-N-S Transfer data is available for CST_PRD 1 to 6.
- August 21, 2015 (v3.0 SOAP & REST): OrganizationEndDate will now return a value in "yyyy-mm-dd" format in PIAP_ENH and PIAP_PREM.
- August 21, 2015 (v3.0 SOAP & REST): MetropolitanStatisticalAreaFIPSCode definition adjusted from integer to string of length 10.
- May 29, 2015 (v2.0 SOAP & REST): SMPL_OWNSHP, GBO and KYC data layers released as part of D&B Direct Onboard API.
- October 3, 2014 (v2.0 SOAP & REST): For Belgium case countries, the calculation for the Financial Embarrassment and Other Special Events indicators has been expanded to encompass additional conditions.
- August 22, 2014 (v2.0 SOAP & REST): Custom data layers are now accepted by the monitoring service. Use GetProductCatalog for list of elements which will be monitored.
Product Request
IMPORTANT: Due to a known issue, please do not include request values for SubmittingOfficeID.
IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.
Overview
When requesting a Custom Product (that excludes small businesses or company principals), a valid D-U-N-S Number for a company, its country code, and the appropriate product code will be required. A trade up option exists to request data for the headquarters when the requested organization is a branch.
When requesting a Custom Product for a small business, you will be required to supply either valid D-U-N-S Number or subject identification number (Subject ID) for a small business, a country code of "US", and the appropriate product code. Subject IDs for organizations may be obtained by using the small business option in the 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-S Number 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.
NOTE: When ordering information for organizations located in Germany, customers are required to provide a valid order reason code.
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 product is entitled as "Custom Product 1 to 6" for D&B Direct 2.0 customers.
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
GET https://direct.dnb.com/V3.0/organizations/804735132/products/CST_PRD_1 Authorization: <My Token>
| 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. |
| {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 |
| 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. |
| 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. |
Endpoint
Use the following endpoint for requesting this product. The {version} is dependent on the underlying service delivering the product.
NOTE: While "organizations" is part of this endpoint, there is no service by this name. Many D&B Direct calls have a similar structure; however, the {version} component is based on the SERVICE to which a given product is associated.
| Endpoint (CustomProduct) |
|---|
| GET https://direct.dnb.com/V{version}/organizations/{DUNS}/products/{productID} |
Testing
This operation is currently unavailable in the D&B Direct sandbox (test) environment.
Trials
When conducting testing in the production environment during a trial period, product requests will be limited to the local market of the customer.
Production
A set of D-U-N-S Numbers is available to D&B Direct 2.0 customers for performing non-billable transactions in the production environment.
Product Response
While data for a particular company may not contain values for each of the business elements, there may be items that are considered by D&B to be "essential" to yield the maximum benefit of a data layer. If any of these essential elements do not contain a value for a particular company, a PD005 response code will be returned, and your organization will not incur a usage credit for the request.
For all codified data delivered by D&B Direct, the response package will include the decoded text value as a data element with the code value attached as an attribute. Refer to the Reference Data Service for access to the D&B standard code tables.
NOTE: The D&B Direct REST implementation uses the BadgerFish approach for JSON with some minor variations.
Specification
The following is a list of the possible data fields returned by this operation in the JSON 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 specific data fields pre-configured for each custom data product will located in the response package as noted.
NOTE: The D-U-N-S Number returned in the response will be a nine-digit zero-padded, numeric value.
Refer to the Financial Statements page for more information on the following:
- Enhanced Financial Statements (US only) are available to customers, providing the latest, most granular data. Customers may see up to three types of Financial Statements.
- Depreciation and Long Term Debt data is returned under various sections of the financial statements for different countries.
Legend: [C] = may be included in a Custom Data product; [M] = may be referenced by the Monitoring process; [M+] = Monitored using an aggregate or attribute XPath.
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.
Empty/NULL Values
A NULL returned for an element indicates that the information was not provided to D&B when the related data items were collected. The absence of a value for a particular item should not be considered indicative of any implied value (e.g., NULL for a boolean indicator is NOT the same as a value of 'false').
Response Codes & Error Handling
Successful service requests will return a CM000 response code in the TransactionResult ResultID field. Otherwise, one of the D&B Direct standard response 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,PD019 and SC001-SC012.
IMPORTANT: PD006 code - Applicable only for US/CA cases when TradeUpIndicator="true" for Risk packets.
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 D-U-N-S Number and product code are submitted on the same calendar day (which is based on Eastern Standard Time [GMT-5]).
Retrieving Archived Copies
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.
NOTE: The default value for ArchiveProductOptOutIndicator is 'true', indicating that the request will NOT be automatically archived.
Business Elements
The business elements returned in a custom product vary based on customer selection.
Exception: Custom Product requests will not return the 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 was configured do not contain a value for a particular company, an error code will be returned, and your organization will not incur a usage credit for the request.
Product Notes
D&B Sales Associates may be provided lists of either Business Element or Response Data Field items (the latter is preferred) for pricing and configuration of up to six Custom Products. Customers may also designate fields in 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.
Throughout the D&B Direct documentation, Business Element and Response Data Field items will be designated with a [C] if they may be included in a Custom Product.
For data items where previous calculations are available (e.g. Financial Stress Score and Commercial Credit Score), be sure to mention the version number to the D&B Sales Associate if an alternate calculation is required.
Once configured, the D&B Sales Associate will provide a Product Code designated for the new Custom Product. Each custom product configuration is only available to the customer account to which it is assigned.
Monitoring Custom Products
To determine which data fields within a custom product will trigger a Monitoring Change Notice, issue a request to the GetProductCatalog function in the Product Catalog Serviceand inspect the MonitorableElementDetail list that is returned.
- © Dun & Bradstreet, Inc. 2019 – 2024. All rights reserved.