Skip to content

SAP ODM API (3)

This API provides access to several CDQ API endpoints according to the SAP One Domain Model (ODM). Requests and responses are mapped from the CDQ data model to ODM in order to simplify service access from SAP systems.

Download OpenAPI description
api-v3.json
api-v3.yaml
Languages
Servers
Mock server

https://developer.cdq.com/_mock/apis/sap-odm-api/v3/api-v3/

Production

https://api.cdq.com/sap-odm/v3/

Bulk Fetch

Bulk Fetch

Operations

Bulk Lookup

Bulk Lookup

Operations

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 ModelSAP One Domain Model
nameformattedOrgName??
identifierstaxNumbers/identifications with their types
legal form categorylegal 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.

CountryFieldField typeTransformation InputTransformation output
CHTax numberCH1CHE-218.608.886 HR/MWSTCHE218608886
Operations

Lookup Business Partners

Request

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.

Security
apiKey
Bodyapplication/jsonrequired

cmd

limitinteger[ 0 .. 1000 ]

Number of items per page. Default value is 10.

Example: "10"
startAfterstring

The ID which is used to read the page.

Example: "5712566172571652"
dataSourcesArray of strings

Filter data sources used during lookup.

Example: ["VIES"]
matchingThresholdnumber(double)[ 0 .. 1 ]

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

Example: "0.5"
maxCandidatesinteger[ 20 .. 200 ]

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

Example: "50"
storagesDataSourcesArray 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.

featuresOnArray of strings(businessPartnerFeaturesDescription)

List of features to be activated.

Items Enum ValueDescription
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 at least one pair of any dnb credentials are provided and given data source is active.

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.

Example: ["ACTIVATE_DATASOURCE_BVD"]
featuresOffArray of strings(businessPartnerFeaturesDescription)

List of features to be deactivated.

Items Enum ValueDescription
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 at least one pair of any dnb credentials are provided and given data source is active.

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.

Example: ["ACTIVATE_DATASOURCE_BVD"]
businessPartnerobject

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.

configurationIdstring

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"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/sap-odm-api/v3/api-v3/referencedata/rest/v4/businesspartners/lookup \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "matchingThreshold": 0,
    "pageSize": 10,
    "page": 0,
    "dataSources": [
      "string"
    ],
    "businessPartner": {
      "names": [
        {
          "value": "string"
        }
      ],
      "identifiers": [
        {
          "value": "string",
          "type": {
            "technicalKey": "string"
          }
        }
      ],
      "legalForm": {
        "value": "string"
      },
      "addresses": [
        {
          "thoroughfares": [
            {
              "value": "string",
              "number": "string"
            }
          ],
          "localities": [
            {
              "value": "string"
            }
          ],
          "administrativeAreas": [
            {
              "value": "string"
            }
          ],
          "postCodes": [
            {
              "value": "string"
            }
          ],
          "country": {
            "shortName": "string"
          }
        }
      ]
    }
  }'

Responses

OK

Bodyapplication/json
totalinteger

Total number of items which can be paged.

Example: "67"
limitinteger

Number of items per page.

Example: "100"
startAfterstring

The ID which is used to read the page.

Example: "5712566172571652"
nextStartAfterstring

Provides a value to be used as a startAfter in next page request.

Example: "5712566172571652"
valuesArray of objects

List of Business Partner Lookup Matches.

goldenRecordobject

Represent a Business Partner record with the highest matching score based on data completeness.

debugInfoobject

Debug information about the lookup. The lookup response contains the matching profile and the matching score. Can be activated by a feature SHOW_DEBUG_INFO.

annotationsArray of objects

The list of annotations.

Response
application/json
{
  "cdqId": "VIES:CZ46981691",
  "dataSource": {
    "aleiPrefix": "VIES",
    "name": "VIES"
  },
  "businessPartner": {
    "names": [ … ],
    "identifiers": [ … ],
    "categories": [],
    "addresses": [ … ],
    "formattedSapRecord": { … },
    "types": []
  }
}

Fetch Business Partner

Request

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

Read more about Golden Record here.

Security
apiKey
Bodyapplication/jsonrequired
cdqIdstring

CDQ ID for Business Partner and address.

Example: "VIES:DE123456789"
businessPartnerobject

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.

featuresOnArray of strings

List of features to be activated.

Items Enum ValueDescription
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

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

<b style="color: white; background: #077fbb; border-radius: 5px; margin-left: 0; padding: 2px 10px; font-size: 14px; vertical-align: super;">BETA</b><br>Finds out whether requested DUNS is a branch or headquarter.

ACTIVATE_DATASOURCE_BVD

Allows to use DVB datasource in golden record.

Example: ["SHOW_RAW_DATA"]
featuresOffArray of strings

List of features to be deactivated.

Items Enum ValueDescription
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

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

<b style="color: white; background: #077fbb; border-radius: 5px; margin-left: 0; padding: 2px 10px; font-size: 14px; vertical-align: super;">BETA</b><br>Finds out whether requested DUNS is a branch or headquarter.

ACTIVATE_DATASOURCE_BVD

Allows to use DVB datasource in golden record.

Example: ["SHOW_RAW_DATA"]
screeningMatchingThresholdnumber

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

Example: "0.8"
configurationIdstring

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"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/sap-odm-api/v3/api-v3/referencedata/rest/v4/businesspartners/fetch \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "cdqId": "VIES:CZ46981691"
  }'

Responses

OK

Bodyapplication/json
debugInfoobject

Reference implementation how to structure external service responses. Can be activated by a feature SHOW_DEBUG_INFO.

statusobject
Message IDTechnical KeyMessage
200000000DEFAULT_OKSuccessful request.
400100001NAME_OR_IDENTIFIER_MISSINGYou have to provide at lease name or identifier.
400100003GR_NON_UNIQUE_RESULTWe found multiple GRs in this business partner, please ensure to submit only 1.
400100002GR_NOT_FOUNDGolden Record not found.
400100004FETCH_STRATEGY_MISSINGYou have to use a fetch strategy if you provide a business partner.
400100005BP_AND_CDQID_PROVIDEDYou have provided a business partner and CDQ ID. Please provide only one.
429000000DEFAULT_TOO_MANY_REQUESTSToo many requests. Your quota is reset in 24h.
500000000DEFAULT_INTERNAL_SERVER_ERRORService failed due to an internal server error. Please contact CDQ Support.
cdqIdstring

Unique identifier for the Business Partner.

Example: "VIES:PL8660001429"
lastSyncAtstring

Last time the Business Partner was synchronized.

Example: "2025-08-27T14:27:22Z"
lastUpdatedAtstring

Last time the Business Partner was updated.

Example: "2025-08-27T14:27:22Z"
dataSourcestring

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
dataSourceNamestring

Name of a data source of a storage.

Example: "Internal customers"
businessPartnerobject

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.

rawRecordArray of objects

Raw record of the Business Partner.

rawRecordJsonobject

Raw record returned by external service in JSON format.

businessPartnerChangesArray of objects

Changes of the Business Partner.

screeningResultobject

Result of the screening process.

additionalInformationArray of objects

Additional information about the Business Partner.

commercialUltimateobject

The details of the Commercial Ultimate for the entity.

domesticCommercialUltimateobject

The details of the Commercial Ultimate for the entity.

legalEntityobject

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.

Response
application/json
{
  "cdqId": "VIES:CZ46981691",
  "dataSource": {
    "aleiPrefix": "VIES",
    "name": "VIES"
  },
  "businessPartner": {
    "names": [ … ],
    "identifiers": [ … ],
    "categories": [],
    "addresses": [ … ],
    "formattedSapRecord": { … },
    "types": []
  }
}