Business Partners

Lookup Business Partners

The Lookup Business Partners endpoint is designed to search for Business Partners within all available data sources. It is specifically crafted to provide data formatted to meet the unique needs of SAP users. The endpoint's primary objective is to offer a seamless integration of CDQ Data Model into the SAP One Domain Model, ensuring that the information is readily accessible and compatible with SAP systems.

CDQ Data Model SAP One Domain Model
name formattedOrgName??
identifiers taxNumbers/identifications with their types
legal form category legal form

Example:

To meet SAP ODM data expectations Lookup Business Partner endpoint checks the technicalKey in the CDQ Identifiers object and compares it with the SAP identificationType's code. Based on this comparison divides identifiers into specific groups e.g. taxNumber.

CDQ Data Model

{
  "identifiers": [
    {
      "type":
        {
          "url": "https://meta.cdq.com/Business_Registration_Number_(Germany)",
          "name": "Business Registration Number",
          "technicalKey": "DE_BNUM"
        },
      "value": "HRB 739690",
      "issuingBody":
        { }
    }
  ]
}

SAP One Domain Model in the jsonRecord

{
  "identifications": [
    {
      "country": { },
      "identificationNumber": "HRB 739690",
      "institute": "Amtsgericht Ulm",
      "identificationType": {
        "code": "BUP002"
      }
    }
  ]
}

To ensure seamless integration and compliance with SAP standards, data transformations are essential. CDQ data model often contains values like 'CHE-218.608.886 HR/MWST' while SAP ODM adheres to a specific format, 'CHE218608886' These transformations bridge the gap between data models, enabling data to pass through internal SAP Data Validation checkpoints. It aligns the data with SAP's stringent standards, making it ready for further processing and validation within SAP systems. These transformations not only harmonize the data but also streamline the validation process, ensuring data accuracy and consistency throughout the SAP ecosystem.

Lookup Business Partner provides alignment with the SAP Factory Standard but can be customized to customer needs.

Country Field Field type Transformation Input Transformation output
CH Tax number CH1 CHE-218.608.886 HR/MWST CHE218608886

Fetch Business Partner

Retrieves the Business Partner based on the Lookup and returning the result of the single record.

Read more about Golden Record here.

SecurityapiKey
Request
Request Body schema: application/json
required
object

Refers to an organizational entity engaged in various facets of another organization's business interactions. This collaborative connection often manifests as a customer, supplier, vendor, or service provider. In the CDQ (Corporate Data Quality) framework, the Business Partner assumes a pivotal role as a core managed entity. Each Business Partner is distinctly and globally identifiable through a unique CDQ ID. All pertinent information, including addresses, identifiers, and hierarchical data, is intricately associated with and linked to the specific Business Partner, ensuring comprehensive management and traceability within the system.

cdqId
string

CDQ ID for Business Partner and address.

Example: "VIES:DE123456789"
configurationId
string

Configuration ID used to set up fetch. If provided, those parameters will be affected. If any of them is provided in this request, will overwrite one from configuration (except for features which are merged):

  • screeningMatchingThreshold
  • featuresOn
  • featuresOff
Example: "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4"
featuresOff
Array of strings

List of features to be deactivated.

Items Enum: Description
ENABLE_SETTINGS

Apply rules stored in organizational settings during curation.

SHOW_DEBUG_INFO

Show additional information regarding request processing, including enabled features, request, request after curation procedure and responses from external services.

SHOW_RAW_DATA

Show raw data returned by external service.

SHOW_RAW_DATA_JSON

Show raw data returned by external service in JSON format.

FORCE_EXTERNAL_CALL

Call external service even when results from data mirrors are available.

SCREEN_BUSINESS_NAMES

Add screeningResult to the Business Partner.

SHOW_COMMERCIAL_ULTIMATE

Fetch Global Commercial Ultimate from BvD or DNB (depending on selected datasource). ACTIVATE_DATASOURCE_DNB, ACTIVATE_MASTER_DATA_EXTENDED or ACTIVATE_MASTER_DATA_LNKG must be active if you want to calculate DNB commercial ultimate.

SHOW_DOMESTIC_COMMERCIAL_ULTIMATE

BETA
Fetch Domestic Commercial Ultimate from DNB. ACTIVATE_DATASOURCE_DNB, ACTIVATE_MASTER_DATA_EXTENDED or ACTIVATE_MASTER_DATA_LNKG must be active if you want to calculate DNB commercial ultimate.

DETECT_LEGAL_ENTITY

BETA
Finds out whether requested DUNS is a branch or headquarter.

ACTIVATE_DATASOURCE_BVD

Allows to use DVB datasource in golden record.

ACTIVATE_DATASOURCE_DNB

Allows to use DNB datasource in golden record.

ACTIVATE_MASTER_DATA_BASIC

Use basic set of datablocks to fetch data.

ACTIVATE_MASTER_DATA_EXTENDED

Use extended set of datablocks to fetch data.

ACTIVATE_MASTER_DATA_MGMT

Use mgmt set of datablocks to fetch data.

ACTIVATE_MASTER_DATA_LNKG

Use lnkg set of datablocks to fetch data.

ACTIVATE_LINKAGE_LNKELI

Fetch LNKELI data.

USE_FETCH_STRATEGY_GOLDEN_RECORD

Use golden record fetch strategy.

Example: ["SHOW_RAW_DATA"]
featuresOn
Array of strings

List of features to be activated.

Items Enum: Description
ENABLE_SETTINGS

Apply rules stored in organizational settings during curation.

SHOW_DEBUG_INFO

Show additional information regarding request processing, including enabled features, request, request after curation procedure and responses from external services.

SHOW_RAW_DATA

Show raw data returned by external service.

SHOW_RAW_DATA_JSON

Show raw data returned by external service in JSON format.

FORCE_EXTERNAL_CALL

Call external service even when results from data mirrors are available.

SCREEN_BUSINESS_NAMES

Add screeningResult to the Business Partner.

SHOW_COMMERCIAL_ULTIMATE

Fetch Global Commercial Ultimate from BvD or DNB (depending on selected datasource). ACTIVATE_DATASOURCE_DNB, ACTIVATE_MASTER_DATA_EXTENDED or ACTIVATE_MASTER_DATA_LNKG must be active if you want to calculate DNB commercial ultimate.

SHOW_DOMESTIC_COMMERCIAL_ULTIMATE

BETA
Fetch Domestic Commercial Ultimate from DNB. ACTIVATE_DATASOURCE_DNB, ACTIVATE_MASTER_DATA_EXTENDED or ACTIVATE_MASTER_DATA_LNKG must be active if you want to calculate DNB commercial ultimate.

DETECT_LEGAL_ENTITY

BETA
Finds out whether requested DUNS is a branch or headquarter.

ACTIVATE_DATASOURCE_BVD

Allows to use DVB datasource in golden record.

ACTIVATE_DATASOURCE_DNB

Allows to use DNB datasource in golden record.

ACTIVATE_MASTER_DATA_BASIC

Use basic set of datablocks to fetch data.

ACTIVATE_MASTER_DATA_EXTENDED

Use extended set of datablocks to fetch data.

ACTIVATE_MASTER_DATA_MGMT

Use mgmt set of datablocks to fetch data.

ACTIVATE_MASTER_DATA_LNKG

Use lnkg set of datablocks to fetch data.

ACTIVATE_LINKAGE_LNKELI

Fetch LNKELI data.

USE_FETCH_STRATEGY_GOLDEN_RECORD

Use golden record fetch strategy.

Example: ["SHOW_RAW_DATA"]
screeningMatchingThreshold
number

The matching threshold. When not set then all entries are taken into consideration.

Example: "0.8"
Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

post/referencedata/rest/v4/businesspartners/fetch
Request samples
application/json
{
  • "cdqId": "VIES:CZ46981691"
}
Response samples
application/json
{
  • "cdqId": "VIES:CZ46981691",
  • "dataSource": {
    },
  • "businessPartner": {
    }
}

Fetch Business Partner

Fetch business partner by CDQ-ID.

SecurityapiKey
Request
Request Body schema: application/json
required
cdqId
string

CDQ ID for business partner and address.

Example: "VIES:PL8660001429"
featuresOff
Array of strings

List of features to be deactivated.

Items Value: Description
SHOW_DEBUG_INFO

Show additional information regarding request processing, including enabled features, and request.

Example: ["SHOW_DEBUG_INFO"]
featuresOn
Array of strings

List of features to be activated.

Items Value: Description
SHOW_DEBUG_INFO

Show additional information regarding request processing, including enabled features, and request.

Example: ["SHOW_DEBUG_INFO"]
Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

post/referencedata/rest/v3/businesspartners/fetch
Request samples
application/json
{
  • "example": "VIES:PL8660001429"
}
Response samples
application/json
{
  • "status": "OK",
  • "message": "Service returned a correct response.",
  • "cdqId": "VIES:PL8660001429",
  • "dataSource": "BR_RF",
  • "businessPartner": {
    }
}

Lookup Business Partners

Perform a Business Partner lookup operation across all available Data Sources. The output of this operation will be a comprehensive list of Business Partners, each accompanied by their respective Data Sources and meticulously calculated matching scores. It is important to note that all accessible data sources are comprehensively documented within the Data_source Category on CDQ Wiki.

The Data Sources are categorized as follows:

  • OPEN: These Data Sources are open to everyone without any registration requirement.
  • FREE: These Data Sources are free to use, but registration is required.
  • COMMERCIAL: These Data Sources are only available to commercial users.

The results of the Business Partner lookup operation are sorted in descending order based on their matching scores. Additionally, the results are conveniently paginated, allowing for efficient navigation through the extensive list. The page size can be effortlessly customized to accommodate specific preferences.

SecurityapiKey
Request
Request Body schema: application/json
required

cmd

object

Refers to an organizational entity engaged in various facets of another organization's business interactions. This collaborative connection often manifests as a customer, supplier, vendor, or service provider. In the CDQ (Corporate Data Quality) framework, the Business Partner assumes a pivotal role as a core managed entity. Each Business Partner is distinctly and globally identifiable through a unique CDQ ID. All pertinent information, including addresses, identifiers, and hierarchical data, is intricately associated with and linked to the specific Business Partner, ensuring comprehensive management and traceability within the system.

configurationId
string

Configuration ID used to set up lookup. If provided, those parameters will be affected. If any of them is provided in this request, will overwrite one from configuration (except for features which are merged):

  • dataSource
  • dataMatchingDefinitionId
  • matchingThreshold
  • maxCandidates
  • pageSize (deprecated)
  • limit
  • featuresOn
  • featuresOff
Example: "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4"
dataSources
Array of strings

Filter data sources used during lookup.

Example: ["VIES"]
featuresOff
Array of strings (businessPartnerFeaturesDescription)

List of features to be deactivated.

Items Enum: Description
ACTIVATE_IDENTIFIER_ONLY_MATCH

Executes lookup based only on identifier. Company names and addresses will not affect results.

ACTIVATE_DATASOURCE_CDQ_POOL

Add results from CDQ Data Sharing Community Data Pool to the lookup results.

ACTIVATE_DATASOURCE_CDL

DEPRECATED Please use ACTIVATE_DATASOURCE_CDQ_POOL instead

ACTIVATE_DATASOURCE_BZST

dd results from Bzst to the lookup results.

ACTIVATE_DATASOURCE_VIES_FOR_ES

Use VIES to check for data correctness (only for spanish records).

ACTIVATE_DATASOURCE_GOOGLEPLACES

Add results from Google Places to the lookup results.

ACTIVATE_DATASOURCE_STORAGES

Add results from organizational data mirrors to the lookup results.

ACTIVATE_DATASOURCE_DNB

Add results from DNB to the lookup results. Works only when in organization setting the dnb credentials are provided or when X-DNB-USER and X-DNB-PASSWORD is set.

ACTIVATE_DATASOURCE_BVD

Add results from BVD to the lookup results.

ACTIVATE_DATASOURCE_NLBR

Add results from the Netherlands Company Register NL.BR to the lookup results. Works only when in organization setting the NL.BR credentials are provided.

ACTIVATE_DATASOURCE_ZEFIX

Add results from the Swiss Business Partner register Zefix.

CURATE_REQUEST

Curate Lookup results with data curation. Active by default.

ENABLE_IDENTIFIER_DERIVATION

Use fuzzy matching when searching with identifiers.

FORCE_EXTERNAL_CALL

Call external service even when results from data mirrors are available.

MATCHING_SCORE_CALCULATION

Calculate matching score. Active by default.

SHOW_DEBUG_INFO

Show additional information regarding request processing, including enabled features, request, request after curation procedure and responses from external services.

SHOW_FORMATTED_ADDRESS

Formats addresses using data curation procedure.

SHOW_FORMATTED_SAP_RECORD

Show formatted sap records in the lookup response.

SHOW_GOLDENRECORD_STANDARD

Calculate golden record for given request.

SHOW_GOLDENRECORD_QUICK

Calculate golden record for given request without performing enrichment.

GOLDENRECORD_INLINE

Includes golden record at first position in array of values

GOLDENRECORD_INLINE_SORTED

Includes golden record in values array in response

SHOW_INCOMPLETE_CANDIDATES

Do not filter out search results without complete address data.

SHOW_REGISTERED_INDIVIDUAL

Show individual personas registered in company registers.

SHOW_SUBSCRIPTION_METADATA

Provide information whether current user is subscribed to given business partner, and overall subscription count.

FORCE_DATA_SOURCES_INTERSECTION

If used with augmentation configuration and data sources are provided in the request, lookup will be performed using the intersection of data sources from request and configuration

ACTIVATE_MASTER_DATA_BASIC_BVD

Returns Master Data Basic from BvD

ACTIVATE_MASTER_DATA_EXTENDED_BVD

Returns Master Data Extended from BvD

ACTIVATE_FINANCIAL_RISK_DATA_BVD

Returns Financial Risk Data from BvD

ACTIVATE_OWNERSHIP_DATA_BVD

Returns Ownership Data from BvD

Example: ["ACTIVATE_DATASOURCE_BVD"]
featuresOn
Array of strings (businessPartnerFeaturesDescription)

List of features to be activated.

Items Enum: Description
ACTIVATE_IDENTIFIER_ONLY_MATCH

Executes lookup based only on identifier. Company names and addresses will not affect results.

ACTIVATE_DATASOURCE_CDQ_POOL

Add results from CDQ Data Sharing Community Data Pool to the lookup results.

ACTIVATE_DATASOURCE_CDL

DEPRECATED Please use ACTIVATE_DATASOURCE_CDQ_POOL instead

ACTIVATE_DATASOURCE_BZST

dd results from Bzst to the lookup results.

ACTIVATE_DATASOURCE_VIES_FOR_ES

Use VIES to check for data correctness (only for spanish records).

ACTIVATE_DATASOURCE_GOOGLEPLACES

Add results from Google Places to the lookup results.

ACTIVATE_DATASOURCE_STORAGES

Add results from organizational data mirrors to the lookup results.

ACTIVATE_DATASOURCE_DNB

Add results from DNB to the lookup results. Works only when in organization setting the dnb credentials are provided or when X-DNB-USER and X-DNB-PASSWORD is set.

ACTIVATE_DATASOURCE_BVD

Add results from BVD to the lookup results.

ACTIVATE_DATASOURCE_NLBR

Add results from the Netherlands Company Register NL.BR to the lookup results. Works only when in organization setting the NL.BR credentials are provided.

ACTIVATE_DATASOURCE_ZEFIX

Add results from the Swiss Business Partner register Zefix.

CURATE_REQUEST

Curate Lookup results with data curation. Active by default.

ENABLE_IDENTIFIER_DERIVATION

Use fuzzy matching when searching with identifiers.

FORCE_EXTERNAL_CALL

Call external service even when results from data mirrors are available.

MATCHING_SCORE_CALCULATION

Calculate matching score. Active by default.

SHOW_DEBUG_INFO

Show additional information regarding request processing, including enabled features, request, request after curation procedure and responses from external services.

SHOW_FORMATTED_ADDRESS

Formats addresses using data curation procedure.

SHOW_FORMATTED_SAP_RECORD

Show formatted sap records in the lookup response.

SHOW_GOLDENRECORD_STANDARD

Calculate golden record for given request.

SHOW_GOLDENRECORD_QUICK

Calculate golden record for given request without performing enrichment.

GOLDENRECORD_INLINE

Includes golden record at first position in array of values

GOLDENRECORD_INLINE_SORTED

Includes golden record in values array in response

SHOW_INCOMPLETE_CANDIDATES

Do not filter out search results without complete address data.

SHOW_REGISTERED_INDIVIDUAL

Show individual personas registered in company registers.

SHOW_SUBSCRIPTION_METADATA

Provide information whether current user is subscribed to given business partner, and overall subscription count.

FORCE_DATA_SOURCES_INTERSECTION

If used with augmentation configuration and data sources are provided in the request, lookup will be performed using the intersection of data sources from request and configuration

ACTIVATE_MASTER_DATA_BASIC_BVD

Returns Master Data Basic from BvD

ACTIVATE_MASTER_DATA_EXTENDED_BVD

Returns Master Data Extended from BvD

ACTIVATE_FINANCIAL_RISK_DATA_BVD

Returns Financial Risk Data from BvD

ACTIVATE_OWNERSHIP_DATA_BVD

Returns Ownership Data from BvD

Example: ["ACTIVATE_DATASOURCE_BVD"]
limit
integer [ 0 .. 1000 ]

Number of items per page. Default value is 10.

Example: "20"
matchingThreshold
number <double> [ 0 .. 1 ]

Matching threshold for the lookup process. Default value is 0.5.

Example: "0.5"
maxCandidates
integer [ 20 .. 200 ]

Maximum number of candidates to be returned. Default value is 50.

Example: "50"
startAfter
string

The ID which is used to read the page.

Example: "5712566172571652"
Array of objects

This field allows to filter data mirrors that will be queried. For each data mirror, data sources can also be filtered. Leave empty to include all available data mirrors in query.

Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

429
Message ID Technical Key Message
429000007 CREDITS_EXCEEDED Credits exceeded. There is not enough credits to execute the request. Contact sales to get additional credits
post/referencedata/rest/v4/businesspartners/lookup
Request samples
application/json
{
  • "matchingThreshold": 0,
  • "pageSize": 10,
  • "page": 0,
  • "dataSources": [
    ],
  • "businessPartner": {
    }
}
Response samples
application/json
{
  • "cdqId": "VIES:CZ46981691",
  • "dataSource": {
    },
  • "businessPartner": {
    }
}

Lookup Business Partners

Lookup a business partner in all available data sources.

SecurityapiKey
Request
Request Body schema: application/json
required
object

An organizational entity engaged in various facets of another organization's business interactions. This collaborative connection often manifests as a customer, supplier, vendor, or service provider. In the CDQ (Corporate Data Quality) framework, the Business Partner assumes a pivotal role as a core managed entity. Each Business Partner is distinctly and globally identifiable through a unique CDQ ID. All pertinent information, including addresses, identifiers, and hierarchical data, is intricately associated with and linked to the specific Business Partner, ensuring comprehensive management and traceability within the system.

dataSources
Array of strings

Filter Data Sources used during lookup.

Example: "VIES"
featuresOff
Array of strings

List of features to be deactivated.

Items Enum: Description
SHOW_DEBUG_INFO

Show additional information regarding request processing, including enabled features, and request.

SHOW_GOLDENRECORD_QUICK

Calculate golden record for given request.

SHOW_GOLDENRECORD_STANDARD

Calculate golden record for given request.

Example: ["SHOW_DEBUG_INFO"]
featuresOn
Array of strings

List of features to be activated.

Items Enum: Description
SHOW_DEBUG_INFO

Show additional information regarding request processing, including enabled features, and request.

SHOW_GOLDENRECORD_QUICK

Calculate golden record for given request.

SHOW_GOLDENRECORD_STANDARD

Calculate golden record for given request.

Example: ["SHOW_DEBUG_INFO"]
limit
integer [ 0 .. 1000 ]

Number of items per page.

Example: "100"
matchingThreshold
number <double> [ 0 .. 1 ]

The matching threshold for the lookup.

Example: "0.5"
maxCandidates
integer [ 20 .. 100 ]

The maximum number of candidates to be returned by the lookup. Default 50.

Example: "50"
page
integer >= 0
Default: 0

Current page number.

Example: "1"
pageSize
integer [ 1 .. 1000 ]

Number of items per page. Default 10.

Example: "100"
startAfter
string

The ID which is used to read the page.

Example: "5712566172571652"
Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

post/referencedata/rest/v3/businesspartners/lookup
Request samples
application/json
{
  • "businessPartner": {
    }
}
Response samples
application/json
{
  • "pageSize": "100",
  • "totals": "67",
  • "page": "1",
  • "limit": "100",
  • "startAfter": "5712566172571652",
  • "nextStartAfter": "5712566172571652",
  • "values": [
    ],
  • "goldenRecord": {
    }
}