How to download a Commercial Ultimate?

Overview

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.

Prerequisites

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

Data Sources activation

Authorization

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.

2. After pasting the API Key, the green padlock will appear.

3. 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

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.

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"]
}

5. To check it by yourself, expand the below section and use the provided methods.

{{
    "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": "https://meta.cdq.com/Business_partner/name/type/local",
                    "name": "Local Name",
                    "technicalKey": "LOCAL"
                },
                "value": "CDQ POLAND SP Z O O",
                "language": { }
            }],
            "identifiers": [{
                "type": {
                    "url": "https://meta.cdq.com/D-U-N-S",
                    "name": "DUNS Number",
                    "technicalKey": "DUNS_ID"
                },
                "value": "421848991",
                "issuingBody": {
                    "name": "Dun & Bradstreet",
                    "url": "https://meta.cdq.com/Business_partner/identifier/issuing_body/CDQ_DNB",
                    "technicalKey": "CDQ_DNB"
                }
            }],
            "status": {},
            "addresses": [],
            "externalId": "421848991",
            "profile":{}
            }
        }
    ]
}}

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.

2. 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"
}

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:

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": [
      "ACTIVATE_MASTER_DATA_EXTENDED",
      "SHOW_COMMERCIAL_ULTIMATE"
    ]
  }

3. 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.

4. To check it by your self, expand the below section and use the provided methods.

curl -i -X POST \
    https://api.cdq.com/referencedata/rest/v3/businesspartners/fetch \
    -H 'Content-Type: application/json' \
    -H 'X-API-KEY: YOUR API KEY' \
    -d '{
        "cdqId": "DNB:480062239",
        "featuresOn": [
            "ACTIVATE_MASTER_DATA_EXTENDED",
            "SHOW_COMMERCIAL_ULTIMATE"
        ]
    }'

{
    "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": {}
    }
}

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.

Summary:

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:

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: developer-portal@cdq.com