How to download a Commercial Ultimate?


This process shows how to determine the decision-making headquarters via a transactional request. The process guides you from the matching of an address over picking the right hit into the actual download of the desired record together with the relation towards its Commercial Ultimate (CU).

Learning Goals

In this tutorial, the user will learn:

  • Searching for Commercial Ultimate in the Lookup-API,
  • Choosing the best candidates,
  • Downloading the Commercial Ultimate via the Business-Partner-Fetch-API.


To follow this tutorial, the below steps must be performed first:

Data Sources activation


To activate the D&B data source, follow the Activate D&B Data Source tutorial.


Before trying CDQ APIs, user must be authenticated:

  1. Paste the API Key in the console's security bar into the X-API-KEY field.
  1. After pasting the API Key, the green padlock will appear.
Be careful

Green padlock doesn't mean that the API Key was pasted correctly.

  1. Check your API key for missing characters or extra space before trying.

No API Key?

  1. Check how to get one on authentication page
  2. Follow the steps above.

Step 1: Business Partner Lookup— Find the right DUNS


If the DUNS-ID of a desired company is known, goes directly to Step 3.

To obtain Commercial Ultimate, the request for the function call to Lookup Business Partners within the CDQ Reference Data API must be prepared. This function takes the address data of your business partner as input arguments, together with the specification of your desired D&B data source.

rg img001

The following table shows which of the D&B products integrated into CDQ are capable of Commercial Ultimate calculation.

Data Source NameD&B Data BlocksCommercial Ultimate Calculation Capability
  1. Prepare the request based on the below example,
  2. In dataSource field, specify the desired D&B data source,
  3. In businessPartner field, provide the name and address details of the Business Partner,
  4. In featuresOn field, the ACTIVATE_DATASOURCE_DNB feature stays.
    "dataSources": ["DNB"],
    "businessPartner": {
        "names": [{"value": "CDQ POLAND SP Z O O"}],
        "addresses": [{
            "thoroughfares": [{"value": "street", "number": ""}],
            "localities": [{"value": ""}],
            "country": {"shortName": "PL"}
    "featuresOn": ["ACTIVATE_DATASOURCE_DNB"]
  1. To check it by yourself, expand the below section and use the provided methods.
Check it by yourself!

Business Partner Lookup

  1. Use the Business Partner Lookup endpoint to send the request:
  2. Select the Lookup Business Partner from DNB from the Request Body's drop-down list,
  1. Check the example body and adjust the request:
    • Add address details of the Business Partner,
    • Chose desired D&B data source,
  2. Send the request using the Send button,
  3. The list of candidates will be displayed in the console.

Response example:

    "pageSize": 10,
    "totals": 10,
    "page": 0,
    "limit": 10,
    "startAfter": "RVtH+Q==",
    "nextStartAfter": "RVtH8w==",
    "values": [{
        "cdqId": "DNB:421848991",
        "dataSource": "DNB",
        "lastSyncAt": "2024-06-17",
        "dataSourceName": "D&B CMPELK Records",
        "matchingProfile": {
            "matchingScores": {
                "overall": {
                    "classification":   {
                        "technicalKey": "MAYBE_MATCH",
                        "name": "Maybe Match"
                    "value": 0.8708133971291866,
                    "explanation": "BP: [overall: [NAME: 0.91; overall: 0.91;]] A: [overall: [THOROUGHFARE: 0.4; overall: 0.4; COUNTRY_SHORTNAME: 0.5; overall: 0.4;]]"
                "businessPartner": {
                    "classification": {
                        "technicalKey": "FULL_MATCH",
                        "name": "Full Match"
                    "value": 0.91
                "address": {}
        "businessPartner": {
            "names": [{
                "type": {
                    "url": "",
                    "name": "Local Name",
                    "technicalKey": "LOCAL"
                "value": "CDQ POLAND SP Z O O",
                "language": { }
            "identifiers": [{
                "type": {
                    "url": "",
                    "name": "DUNS Number",
                    "technicalKey": "DUNS_ID"
                "value": "421848991",
                "issuingBody": {
                    "name": "Dun & Bradstreet",
                    "url": "",
                    "technicalKey": "CDQ_DNB"
            "status": {},
            "addresses": [],
            "externalId": "421848991",

The list of candidates was successfully obtained!

Step 2: Candidate Matching - Choose the right candidate from the candidate list

Upon submitting a request to the CDQ Lookup API, the API will return a list of candidates that match the input record, sorted by a matching score denoting the proximity of the input record to the candidates. If the desired company is not found, modify the query and resend the request until the right match is identified in the candidate list. In short, the output can be succinctly summarized in a table referred to as the "candidate list".

  1. Check the list of received candidates.

For better readability, this candidate list was extracted from the Lookup-API into a table. It is not the default output of the API. Choose your desired candidate or refine the lookup and start over.

rg img003
  1. Select the right candidate by checking the address details and the DUNS number.

The example company with the highest-matching overall score:

    "name": "CDQ POLAND SP Z O O",
    "cdqId": "DNB:421848991",
    "duns_id": "421848991"

The candidate with the highest-matching score is selected.

Step 3: Data Enrichment— Request Data Package with Commercial Ultimate

Choose a CDQ ID from the hit lists and use the CDQ API to request the D&B product with the Commercial Ultimate. The specific API call to be used is the Fetch Business Partner. This API call can be customized using various "feature toggles". Feature toggles are switches that can activate or deactivate specific functions within the API. For our unique scenario of downloading a record from D&B and calculating the "commercial ultimate", the following feature toggles are to be used:

Feature ToggleExplanation
ACTIVATE_MASTER_DATA_EXTENDEDThis activates the download of your licensed D&B Product e.g. "Master Data Extended" as base for your commercial Ultimate detection. This is the starting point of he upward-looking Commercial-Ultimate detection path. Note that only data products containing the data block for corporate linkages are capable of Commercial Ultimate detection.
SHOW_COMMERCIAL_ULTIMATEThis switches on the calculation of the commercial ultimate. The toggle will add an additional hierarchy "commercialUltimate" besides the direct parent, the domestic parent and the global ultimate into the D&B data. Note that this is calculated by CDQ utilizing the list of parents up to the top of the family tree and that transactional requests are performed towards D&B in order to calculate the data. Please make sure to plan the quota with your D&B representative.
SHOW_DOMESTIC_COMMERCIAL_ULTIMATEThis switches on the calculation of the domestic commercial ultimate in the same country of the requested business partners location. The toggle will add an additional hierarchy "domesticCommercialUltimate" besides the direct parent, the domestic parent and the global ultimate into the D&B data. Note that this is calculated by CDQ utilizing the list of parents up to the top of the family tree and that transactional requests are performed towards D&B in order to calculate the data. Please make sure to plan the quota with your D&B representative.
SHOW_RAW_DATA_JSONOptional. Generally, the CDQ-APIs transform the data given from each data source into a harmonized CDQ data model in order to reach compatibility between sources and to minimize integration effort and to reach flexibility in data sourcing. Optionally, this toggle switches the delivery of the original D&B data elements used here, on.
ACTIVATE_DATASOURCE_DNB_STORAGEUses the data from your D&B Data storage in order not to consume too much quota on the D&B side. If Monitoring is enabled, the D&B storage will always contain the most recent data from D&B.

To prepare the proper request:

  1. Adjust given example,
  2. Use the cdqId field to search for Commercial Ultimate by the DUNS number.
    "cdqId": "DNB:480062239",
    "featuresOn": [
  1. Check the response:

The Business Partner data for the requested DUNS will be found in the response. Additionally, the Commercial Ultimate with its DUNS, primary name, address, and the detailed response of D&B will be included.

rg img002
  1. To check it by your self, expand the below section and use the provided methods.
Check it by your self!

Fetch Business Partner

  1. Use the Fetch Business Partner endpoint to send the request,
  2. Use the example Fetch Business PPartner for Commercial Ultimate from the console's dropdown list or build your own,

Curl Example

Check the below example of the curl request to fetch the Business Partner with the Commercial Ultimate:

curl -i -X POST \ \
    -H 'Content-Type: application/json' \
    -d '{
        "cdqId": "DNB:480062239",
        "featuresOn": [
  1. Check the response in the console.
    "cdqId": "DNB:480062239",
    "lastSyncAt": "2024-03-07",
    "dataSource": "DNB.MASTER.DATA.EXTENDED",
    "dataSourceName": "DNB Master Data Extended Records",
    "businessPartner": {},
    "commercialUltimate": {
        "duns": "480062239",
        "primaryName": "CDQ AG",
        "primaryAddress": {},
        "dataBlock": {}

The data package with the Commercial Ultimate was successfully obtained!

Optional: Domestic Commercial Ultimate

The Commercial Ultimate is usually calculated globally. When conducting business with a partner company, it's often also important to identify a domestic decision-maker within the same country as your business partner. This ensures smoother communication, quicker decision-making processes, and better alignment with local regulations and business practices. Here are some key reasons why having a domestic decision-taker is beneficial:

  1. Cultural and Regulatory Alignment: Domestic decision-makers understand local business etiquette, cultural nuances, and regulatory requirements, which can facilitate more effective and respectful negotiations and collaborations.
  2. Time Zone and Language Convenience: Operating in the same time zone and speaking the same language eliminates delays caused by time differences and language barriers, allowing for more timely responses and clearer communication.
  3. Faster Decision-Making: Local decision-makers are more accessible for urgent matters and can make decisions more quickly without the need for lengthy international communications.
  4. Market Insight: Domestic decision-makers have a better grasp of the local market conditions, consumer behavior, and competitive landscape, which can lead to more informed and strategic business decisions.
  5. Risk Mitigation: Understanding and complying with local laws and regulations is essential for mitigating legal and operational risks. Domestic decision-makers are more adept at navigating the local regulatory environment.
By identifying a domestic decision maker, businesses can ensure more efficient and effective partnerships, leading to better outcomes and stronger relationships with their business partners. The calculation of a domestic Commercial Ultimate is enabled with the option "SHOW_DOMESTIC_COMMERCIAL_ULTIMATE".


The process of identifying and utilizing Commercial Ultimate data is integral to effective corporate governance, risk management, and strategic planning, providing a comprehensive view of corporate structures and their decision-making nodes. In summary, two API Functions need to be called for a technical implementation:

1) Lookup Business Partners - The Search Function of CDQ takes an address as input resulting in a candidate list of possible hits ordered by relevance 2) Fetch Business Partner - The Data Download of the Business Partner Master Data. Upon the CDQ-ID with a DUNS-Number together with the feature toggles "ACTIVATE_MASTER_DATA_EXTENDED", "SHOW_COMMERCIAL_ULTIMATE", "SHOW_DOMESTIC_COMMERCIAL_ULTIMATE" and "ACTIVATE_DATASOURCE_DNB_STORAGE", the API will deliver Master Data together with its Commercial Ultimate.

Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!

Mail our developer-portal team: