Skip to content

Referencedata API (3)

This API provides services to search and read reference data

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

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

Production

https://api.cdq.com/referencedata/rest/

Business Partners

Everything about Business Partners

Operations

Fetch Business Partner

Request

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

Security
apiKey
Headers
X-DNB-USERstringDeprecated

Credentials are now stored in Data Source Settings in Cloud Apps.

Example: dnb_consumer_key
X-DNB-PASSWORDstringDeprecated

Credentials are now stored in Data Source Settings in Cloud Apps.

Example: dnb_consumer_secret
Bodyapplication/jsonrequired
cdqIdstringrequired

CDQ ID for Business Partner and address.

Example: "VIES:DE123456789"
featuresOnArray of strings(BusinessPartnerFetchFeaturesDesc)

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: ["ENABLE_SETTINGS"]
featuresOffArray of strings(BusinessPartnerFetchFeaturesDesc)

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: ["ENABLE_SETTINGS"]
screeningMatchingThresholdnumber

The matching threshold for compliance screening. If set and a fetch result is not above threshold, it will not be returned.

Example: "0.5"
configurationIdstring(ReferenceDataFetchConfigurationId)

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"
outboundMappingstring(OutboundMapping)Deprecated

If outboundMapping is set, business partner is transformed to the desired mapped record in a key-value representation.

Avaliable mappings:

  • SAP
Example: "SAP"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/v3/businesspartners/fetch \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "cdqId": "VIES:CZ46981691"
  }'

Responses

OK

Bodyapplication/json
debugInfoobject(FetchDebugInfo)

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

statusstring

status:

  • OK - Service returned a correct response.
  • FAILED - Call to external service failed.
  • INVALID_INPUT - Given input parameter is invalid or entry not found.
  • AUTHORIZATION_FAILED - Authorization to external service does not succeed.
  • EXTERNAL_QUOTA_EXCEEDED - External service quota is exceeded. Not applies to CDQ quota.
Example: "OK"
messagestring

Additional information regarding results.

Example: "Given input parameter is invalid or entry not found."
cdqIdstring

Unique identifier for the Business Partner.

Example: "VIES:PL8660001429"
lastSyncAtstring

Last time the Business Partner was synchronized.

Example: "2025-09-12T14:57:59Z"
lastUpdatedAtstring

Last time the Business Partner was updated.

Example: "2025-09-12T14:57:59Z"
dataSourcestring(BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
dataSourceNamestring(BusinessPartnerStorageDataSourceName)

Name of a data source of a storage.

Example: "Internal customers"
businessPartnerobject(BusinessPartner)

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(KeyValueItem)

List of raw records returned by external service.

rawRecordJsonobject(RawRecordJson)

Raw record returned by external service in JSON format.

mappedRecordobject(MappedRecord)

Custom-representation of a data record.

businessPartnerChangesArray of objects(PropertyChange)

List of changes in the Business Partner.

screeningResultobject(BusinessPartnerFetchScreeningResult)

Result of the screening process.

additionalInformationArray of objects(AdditionalInformation)
commercialUltimateobject(CommercialUltimate)

The details of the Commercial Ultimate for the entity.

domesticCommercialUltimateobject(CommercialUltimate)

The details of the Commercial Ultimate for the entity.

legalEntityobject(BusinessPartner)

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": "VIES",
  "businessPartner": {
    "names": [ … ],
    "identifiers": [ … ],
    "categories": [],
    "addresses": [ … ],
    "formattedSapRecord": { … },
    "types": []
  }
}

Fetch Business Partner Relations

Request

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

Security
apiKey
Bodyapplication/jsonrequired
cdqIdstring

CDQ ID for Business Partner and address.

Example: "VIES:DE123456789"
limitinteger(Limit)

Number of items per page.

Example: "100"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
endedAfterstring

Find relations which endedAt is after given date.

Example: "2025-09-12T14:57:59Z"
endedBeforestring

Find relations which endedAt is before given date.

Example: "2025-09-12T14:57:59Z"
startedAfterstring

Find relations which startedAt is after given date.

Example: "2025-09-12T14:57:59Z"
startedBeforestring

Find relations which startedAt is before given date.

Example: "2025-09-12T14:57:59Z"
classTechnicalKeystring

Filter by class technical key.

Example: "BUSINESS_PARTNER_RELATION_CLASS_LEI_HIERARCHY"
typeTechnicalKeystring

Filter by type.

Example: "LEI_DIRECT_PARENT"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/v3/businesspartners/fetchrelations \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "cdqId": "LEI:CZ46981691"
  }'

Responses

OK

Bodyapplication/json
nextStartAfterstring(NextStartAfter)

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

Example: "5712566172571652"
limitinteger(Limit)

Number of items per page.

Example: "100"
totalinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
valuesArray of objects(BusinessPartnerRelation)

List of Business Partner relations.

Response
application/json
{
  "nextStartAfter": "5712566172571652",
  "limit": "100",
  "total": "67",
  "values": [
    { … }
  ]
}

Fetch Batch Business Partners

Request

Retrieves the Business Partners based on the Lookup and returning the result of the multiple records.

Security
apiKey
Headers
X-DNB-USERstringDeprecated

Credentials are now stored in Data Source Settings in Cloud Apps.

Example: dnb_consumer_key
X-DNB-PASSWORDstringDeprecated

Credentials are now stored in Data Source Settings in Cloud Apps.

Example: dnb_consumer_secret
Bodyapplication/jsonrequired
cdqIdsArray of strings

List of CDQ IDs for Business Partner and address.

Example: ["VIES:DE123456789"]
featuresOnArray of strings(BusinessPartnerFetchFeaturesDesc)

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: ["ENABLE_SETTINGS"]
featuresOffArray of strings(BusinessPartnerFetchFeaturesDesc)

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: ["ENABLE_SETTINGS"]
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/v3/businesspartners/fetch-batch \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "cdqIds": [
      "LEI:529900IM9PTBU50P5M88L",
      "PL.NOBR:5220000080"
    ]
  }'

Responses

OK

Bodyapplication/jsonArray [
debugInfoobject(FetchDebugInfo)

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

statusstring

status:

  • OK - Service returned a correct response.
  • FAILED - Call to external service failed.
  • INVALID_INPUT - Given input parameter is invalid or entry not found.
  • AUTHORIZATION_FAILED - Authorization to external service does not succeed.
  • EXTERNAL_QUOTA_EXCEEDED - External service quota is exceeded. Not applies to CDQ quota.
Example: "OK"
messagestring

Additional information regarding results.

Example: "Given input parameter is invalid or entry not found."
cdqIdstring

Unique identifier for the Business Partner.

Example: "VIES:PL8660001429"
lastSyncAtstring

Last time the Business Partner was synchronized.

Example: "2025-09-12T14:57:59Z"
lastUpdatedAtstring

Last time the Business Partner was updated.

Example: "2025-09-12T14:57:59Z"
dataSourcestring(BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
dataSourceNamestring(BusinessPartnerStorageDataSourceName)

Name of a data source of a storage.

Example: "Internal customers"
businessPartnerobject(BusinessPartner)

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(KeyValueItem)

List of raw records returned by external service.

rawRecordJsonobject(RawRecordJson)

Raw record returned by external service in JSON format.

mappedRecordobject(MappedRecord)

Custom-representation of a data record.

businessPartnerChangesArray of objects(PropertyChange)

List of changes in the Business Partner.

screeningResultobject(BusinessPartnerFetchScreeningResult)

Result of the screening process.

additionalInformationArray of objects(AdditionalInformation)
commercialUltimateobject(CommercialUltimate)

The details of the Commercial Ultimate for the entity.

domesticCommercialUltimateobject(CommercialUltimate)

The details of the Commercial Ultimate for the entity.

legalEntityobject(BusinessPartner)

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
[
  {
    "debugInfo": { … },
    "status": "OK",
    "message": "Given input parameter is invalid or entry not found.",
    "cdqId": "VIES:PL8660001429",
    "lastSyncAt": "2025-09-12T14:57:59Z",
    "lastUpdatedAt": "2025-09-12T14:57:59Z",
    "dataSource": "648824a691d8d2503d65103e",
    "dataSourceName": "Internal customers",
    "businessPartner": { … },
    "rawRecord": [ … ],
    "rawRecordJson": {},
    "mappedRecord": { … },
    "businessPartnerChanges": [ … ],
    "screeningResult": { … },
    "additionalInformation": [ … ],
    "commercialUltimate": { … },
    "domesticCommercialUltimate": { … },
    "legalEntity": { … }
  }
]

Simplified Lookup Business Partners

Request

Perform a comprehensive Business Partner lookup across all accessible Data Sources. This endpoint offers a simplified HTTP GET method for conducting the lookup. However, it only offers a limited set of default features. For the complete range of features, it is recommended to utilize the HTTP POST version.

Security
apiKey
Query
namestring

The name of the Business Partner.

Example: name=CDQ
countrystring

The country (ISO code) of the Business Partner address.

Example: country=CH
localitystring

The locality (city) of the Business Partner address.

Example: locality=Sankt Gallen
postCodestring

The postal code of the Business Partner address.

Example: postCode=9000
thoroughfarestring

The thoroughfare (street, incl. house number) of the Business Partner address.

Example: thoroughfare=Lukasstrasse 4
identifierstring

An identifier (the value, number, payload) of the Business Partner.

Example: identifier=CHCHE218608886
identifierTypestring

The type of given identifier of the Business Partner.

Example: identifierType=BVD_ID
curl -i -X GET \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/v3/businesspartners/lookup \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
pageSizeinteger(PageSize)[ 1 .. 1000 ]

Number of items per page. Default 10.

Example: "10"
totalsinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
pageinteger(Page)>= 0

Current page number.

Default 0
Example: "1"
limitinteger(Limit)

Number of items per page.

Example: "100"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
nextStartAfterstring(NextStartAfter)

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

Example: "5712566172571652"
valuesArray of objects(BusinessPartnerLookupMatch)

List of Business Partner Lookup Matches.

goldenRecordobject(GoldenRecord)

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

debugInfoobject

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

annotationsArray of objects(Annotations)

The list of annotations.

Response
application/json
{
  "pageSize": "10",
  "totals": "67",
  "page": "1",
  "limit": "100",
  "startAfter": "5712566172571652",
  "nextStartAfter": "5712566172571652",
  "values": [
    { … }
  ],
  "goldenRecord": {
    "cdqId": "VIES:PL1132639219",
    "matchingProfile": { … },
    "businessPartner": { … },
    "mappedRecord": { … },
    "metadata": [ … ],
    "businessPartnerChanges": [ … ]
  },
  "debugInfo": {
    "features": [ … ],
    "request": { … },
    "curatedRequest": { … },
    "externalServiceResponses": [ … ]
  },
  "annotations": [
    { … }
  ]
}

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
Headers
X-DNB-USERstringDeprecated

Credentials are now stored in Data Source Settings in Cloud Apps.

Example: dnb_consumer_key
X-DNB-PASSWORDstringDeprecated

Credentials are now stored in Data Source Settings in Cloud Apps.

Example: dnb_consumer_secret
Bodyapplication/jsonrequired

cmd

businessPartnerobject(BusinessPartnerParam)

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.

dataSourcesArray of strings

Filter data sources used during lookup

Example: ["VIES"]
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.

matchingThresholdnumber(double)[ 0 .. 1 ]

Matching threshold for the lookup. Default 0.5.

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

Maximum number of candidates to be returned. Default 10.

Example: "20"
pageSizeinteger(PageSize)[ 1 .. 1000 ]

Number of items per page. Default 10.

Example: "10"
pageinteger>= 0

Current page number.

Default 0
Example: "1"
limitinteger[ 0 .. 1000 ]

Number of items per page.

Example: "100"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
featuresOnArray of strings(businessPartnerFeaturesDescription)

The 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)

The 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"]
configurationIdstring(ReferenceDataConfigurationId)

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"
dataSourcestringDeprecated

Data source to be used for the lookup.

Example: "VIES"
dataMatchingDefinitionIdstringDeprecated

The data matching definition ID to be used for the lookup. If set, it will overwrite the default data matching definition. If not set, the default data matching definition will be used.

Example: "6461e6113b1865304b3038b6"
outboundMappingstring(OutboundMapping)Deprecated

If outboundMapping is set, business partner is transformed to the desired mapped record in a key-value representation.

Avaliable mappings:

  • SAP
Example: "SAP"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/v3/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
pageSizeinteger(PageSize)[ 1 .. 1000 ]

Number of items per page. Default 10.

Example: "10"
totalsinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
pageinteger(Page)>= 0

Current page number.

Default 0
Example: "1"
limitinteger(Limit)

Number of items per page.

Example: "100"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
nextStartAfterstring(NextStartAfter)

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

Example: "5712566172571652"
valuesArray of objects(BusinessPartnerLookupMatch)

List of Business Partner Lookup Matches.

goldenRecordobject(GoldenRecord)

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

debugInfoobject

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

annotationsArray of objects(Annotations)

The list of annotations.

Response
application/json
{
  "pageSize": 10,
  "totals": 2,
  "page": 0,
  "limit": 10,
  "startAfter": "RVtH+Q==",
  "nextStartAfter": "RVtH8w==",
  "values": [
    { … },
    { … }
  ]
}

Search Business Partners

Request

Use for single queries to quickly find a Business Partner. User have to verify the results. To be used when Business Partner is not normalized e.g. Company Name and Address are in one line.

Security
apiKey
Bodyapplication/jsonrequired

cmd

querystringnon-empty

Pattern which will be used to search in multiple fields.

Example: "CDQ Lukasstrasse 4, Sankt Gallen 9000"
pageSizeinteger(PageSize)[ 1 .. 1000 ]

Number of items per page. Default 10.

Example: "10"
pageinteger(Page)>= 0

Current page number.

Default 0
Example: "1"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/v3/businesspartners/search \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "query": "CDQ, 50-078 Wrocław"
  }'

Responses

OK

Bodyapplication/json
pageSizeinteger(PageSize)[ 1 .. 1000 ]

Number of items per page. Default 10.

Example: "10"
totalsinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
pageinteger(Page)>= 0

Current page number.

Default 0
Example: "1"
valuesArray of objects(BusinessPartnerSearchResultEntry)

List of Business Partners search entry.

Response
application/json
{
  "pageSize": "10",
  "totals": "67",
  "page": "1",
  "values": [
    { … }
  ]
}

Generate Golden Record

Request

Create a Business Partner's golden record by computing the matching score using data completeness. The golden record generated has the highest matching score.

Security
apiKey
Bodyapplication/jsonrequired

cmd

cdqIdstring

CDQ ID of the Golden Record.

Example: "VIES:PL1132639219"
featuresOnArray of strings(BusinessPartnerGoldenRecordFeatureEnum)

List of features to be activated.

Items ValueDescription
SHOW_FORMATTED_SAP_RECORD

Show formatted sap records in the golden record response.

Example: ["SHOW_FORMATTED_SAP_RECORD"]
configurationIdstring(ConfigurationId)

Uniquely identifies a configuration.

Example: "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4"
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/v3/businesspartners/goldenrecord \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "cdqId": "VIES:PL1132639219",
    "featuresOn": [
      "SHOW_FORMATTED_SAP_RECORD"
    ],
    "configurationId": "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4"
  }'

Responses

OK

Bodyapplication/json
cdqIdstring

CDQ ID of the Golden Record.

Example: "VIES:PL1132639219"
matchingProfileobject(MatchingProfile)

Matching profile used for the match. It contains the matching threshold and the matching scores.

businessPartnerobject(BusinessPartner)

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.

mappedRecordobject(MappedRecord)

Custom-representation of a data record.

metadataArray of objects(Metadata)

Metadata of the Golden Record.

businessPartnerChangesArray of objects(PropertyChange)
Response
application/json
{
  "cdqId": "VIES:PL1132639219",
  "matchingProfile": {
    "matchingScores": { … }
  },
  "businessPartner": {
    "names": [ … ],
    "legalForm": { … },
    "identifiers": [ … ],
    "categories": [ … ],
    "status": { … },
    "addresses": [ … ],
    "externalId": "The ID managed in the customer's SAP systems.",
    "profile": { … },
    "formattedSapRecord": { … },
    "relations": [ … ],
    "types": [ … ],
    "externalContext": { … },
    "jsonRecord": {},
    "bankAccounts": [ … ]
  },
  "mappedRecord": {
    "attributes": [ … ]
  },
  "metadata": [
    { … }
  ],
  "businessPartnerChanges": [
    { … }
  ]
}

Create Supplier Gateway Record

Request

Creates a new Supplier Gateway record by providing the necessary information and returns the created record.

Security
apiKey
Bodyapplication/jsonrequired
supplierGatewayobject(SupplierGatewayCreateBody)

Complete body of the Supplier Gateway Record.

curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/sgw/businesspartners \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "supplierGateway": {
      "CompanyName": "Acme Corporation",
      "EIN": "12-3456789",
      "SupplierNumber": "SUP12345",
      "Address": "123 Main St",
      "Address2": "Suite 100",
      "City": "Springfield",
      "State": "IL",
      "Country": "USA",
      "Zip": "62701",
      "ZipPlus": "62701-1234",
      "Phone": "(123) 456-7890",
      "Category": "Manufacturing",
      "Ethnicity": "Not disclosed",
      "ContactFirstName": "John",
      "ContactLastName": "Doe",
      "ContactEmail": "johndoe@example.com",
      "RequiredtoReport": "Yes",
      "YearEstablished": "2000",
      "NumberOfEmployee": "100",
      "Capabilities": "Manufacturing, Distribution",
      "Duns": "15-048-3782",
      "Naics": "541511",
      "ProductListing": "Product A, Product B",
      "ServiceListing": "Service X, Service Y",
      "Certificates": [
        {
          "CertID": "CERT12345",
          "CertNo": "12345",
          "CertifiedDate": "2025-09-12T14:57:59Z",
          "ExpirationDate": "2025-09-12T14:57:59Z",
          "Attachments": {
            "Title": "Certificate Document",
            "Url": "https://example.com/certificate.pdf"
          }
        }
      ]
    }
  }'

Responses

successful operation

Body
Codestring

Code representing the status of the supplier gateway.

Example: "200"
Messagestring

Message providing additional information about the status of the supplier gateway.

Example: "Supplier gateway successfully created"
Supplierobject

Containing details about the supplier.

Response
{
  "Code": "200",
  "Message": "Supplier gateway successfully created",
  "Supplier": {
    "SupplierNumber": "SUP12345",
    "TaxID": "12-3456789",
    "CompanyName": "Acme Corporation",
    "ContactName": "John Doe",
    "Address": "123 Main St, Springfield, IL",
    "City": "Springfield",
    "State": "IL",
    "Country": "USA",
    "Zip": "62701",
    "ZipPlus": "62701-1234",
    "Phone": "(123) 456-7890",
    "Fax": "(123) 456-7891",
    "Email": "contact@acme.com",
    "Web": "https://www.acme.com",
    "Duns": "15-048-3782",
    "yearEstablished": "2000",
    "NumberOfEmployee": "100",
    "Capability": "Manufacturing, Distribution",
    "Status": "Active",
    "Acct": "ACC12345",
    "LastAct": "2025-09-12T14:57:59Z",
    "SBASDB": "Yes",
    "Hub": "Yes",
    "HubExp": "2025-09-12T14:57:59Z",
    "Validated": "Yes",
    "Preg": "PREG12345",
    "PregStart": "2025-09-12T14:57:59Z",
    "PregComp": "2025-09-12T14:57:59Z",
    "PregStat": "Completed",
    "Mospnd18": "MOSPND12345",
    "Moamt18": "MOAMT12345",
    "MasterSupplierNo": "MSUP12345",
    "Tier2Required": "Yes",
    "Categories": [ … ],
    "Ethnicities": [ … ],
    "Certifications": [ … ],
    "Banks": [ … ]
  }
}

Fetch Supplier Gateway Record

Request

Fetches a Supplier Gateway record by providing the necessary information and returns the fetched record.

Security
apiKey
Bodyapplication/jsonrequired
cdqIdstring

CDQ ID of the supplier gateway record to fetch.

Example: "VIES:DE119267630"
supplierNumberstring

Supplier Number to fetch the Record.

Example: "SUP12345"
featuresOnArray of strings

List of features to be activated.

Items ValueDescription
ENRICH_MINORITY_INDICATOR

Enrich the supplier gateway record with the minority indicator.

Example: ["ENRICH_MINORITY_INDICATOR"]
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/sgw/businesspartners/fetch \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "cdqId": "VIES:DE119267630",
    "supplierNumber": "SUP12345",
    "featuresOn": [
      "ENRICH_MINORITY_INDICATOR"
    ]
  }'

Responses

successful operation

Body
cdqIdstring

The CDQ ID of the supplier gateway.

Example: "VIES:DE119267630"
supplierGatewayobject(SupplierGateway)

A gateway for a supplier.

Provides information such as:

  • status,
  • contact details,
  • certifications,
  • bank information,
  • business categories.
minorityIndicatorobject(MinorityIndicator)

The minority indicator determines the minority group to which a vendor belongs. Usually, the minority indicator is only relevant in the United States and it is used for reporting purposes only. There is a corresponding SAP field in the vendor master for maintaining the minority indicator.

This feature is as of today dependent on data provided by a US based company: SupplierGateway.

Additional documentation can be found here.

Response
{
  "cdqId": "VIES:DE119267630",
  "supplierGateway": {
    "Code": "200",
    "Message": "Supplier gateway successfully created",
    "Supplier": { … }
  },
  "minorityIndicator": {
    "value": "Social enterprise"
  }
}

Fetch DNB RecordDeprecated

Request

Fetch D&B record by CDQ-ID. It is possible to read:

  • legacy CMPELK data
  • Data Blocks defined here

Fetch CMPELK

To fetch the CMPELK object no features have to be activated.

POST /dnb/businesspartners/fetch
{
  "cdqId": "DNB:123456789"
}

Fetch Data Blocks

It is possible to read pre-defined Data Blocks

Fetch pre-defined Data Blocks

There are 2 features with pre-defined data blocks:

  • ACTIVATE_MASTER_DATA_BASIC uses following data blocks:
    • COMPANYINFO_L1_V1
  • ACTIVATE_MASTER_DATA_EXTENDED uses following data blocks:
    • COMPANYINFO_L1_V1
    • COMPANYINFO_L2_V1
    • HIERARCHYCONNECTIONS_L1_V1
    • PRINCIPALSCONTACTS_L2_V2
POST /dnb/businesspartners/fetch
{
  "cdqId": "DNB:123456789",
  "featuresOn": [
    "ACTIVATE_MASTER_DATA_BASIC"
  ]
}

Fetch LNKELI

It is possible to fetch LNKELI data:

POST /dnb/businesspartners/fetch
{
  "cdqId": "DNB:123456789",
  "featuresOn": [
    "ACTIVATE_LINKAGE_LNKELI"
  ]
}
Security
apiKey
Headers
X-DNB-USERstring

Dnb Consumer Key.

Example: dnb_consumer_key
X-DNB-PASSWORDstring

Dnb Consumer Secret.

Example: dnb_consumer_key
Body
required
cdqIdstring

Unique identifier for the Business Partner.

Example: "VIES:PL8660001429"
featuresOnArray of strings(DnbFetchFeature)

List of features to be activated.

Items Enum ValueDescription
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 management set of datablocks to fetch data.

ACTIVATE_MASTER_DATA_LNKG

Use linkage set of datablocks to fetch data.

ACTIVATE_LINKAGE_LNKELI

Fetch LNKELI data.

ACTIVATE_DATASOURCE_DNB_STORAGE

Checks storage and skips call to D&B if results were found.

ACTIVATE_DATASOURCE_DNB_STORAGE_ONLY

Skips call to D&B entirely and only checks storage for results.

ENRICH_COMMERCIAL_ULTIMATE

Uses additional cmpelk calls to load whole organization hierarchy and detect global ultimate.

ENABLE_SETTINGS

Apply rules stored in organizational settings during curation.

SHOW_CDQ_RECORD

Return also Dnb record mapped to cdq model.

Example: ["ACTIVATE_MASTER_DATA_BASIC"]
featuresOffArray of strings(DnbFetchFeature)

List of features to be deactivated.

Items Enum ValueDescription
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 management set of datablocks to fetch data.

ACTIVATE_MASTER_DATA_LNKG

Use linkage set of datablocks to fetch data.

ACTIVATE_LINKAGE_LNKELI

Fetch LNKELI data.

ACTIVATE_DATASOURCE_DNB_STORAGE

Checks storage and skips call to D&B if results were found.

ACTIVATE_DATASOURCE_DNB_STORAGE_ONLY

Skips call to D&B entirely and only checks storage for results.

ENRICH_COMMERCIAL_ULTIMATE

Uses additional cmpelk calls to load whole organization hierarchy and detect global ultimate.

ENABLE_SETTINGS

Apply rules stored in organizational settings during curation.

SHOW_CDQ_RECORD

Return also Dnb record mapped to cdq model.

Example: ["ACTIVATE_MASTER_DATA_BASIC"]
curl -i -X POST \
  https://developer.cdq.com/_mock/apis/referencedata-api/api-v3/dnb/businesspartners/fetch \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "cdqId": "VIES:PL8660001429",
    "featuresOn": [
      "ACTIVATE_MASTER_DATA_BASIC"
    ],
    "featuresOff": [
      "ACTIVATE_MASTER_DATA_BASIC"
    ]
  }'

Responses

OK

Body
cmpelkV2object(CmpelkV2)

The details of the entity.

dataBlockobject(DataBlock)

A data block is a collection of data elements that are logically grouped together. Enables you to retrieve data on a specific entity or category.

lnkeliobject(CmpelkV2)

The details of the entity.

commercialUltimateobject(CommercialUltimate)

The details of the Commercial Ultimate for the entity.

cdqRecordobject(schemas-BusinessPartner)

An organization which has some degree of involvement with another organization's business dealings. Typically, a company's business partner is another company in the role of a customer, a supplier, a vendor, or a service provider. In the CDL context, the business partner is the core managed entity. A business partner is globally uniquely identifiable by a CDL ID, and all managed information such as addresses, documents, and hierarchies is linked to a business partner.

cdqCommercialUltimateobject(schemas-BusinessPartner)

An organization which has some degree of involvement with another organization's business dealings. Typically, a company's business partner is another company in the role of a customer, a supplier, a vendor, or a service provider. In the CDL context, the business partner is the core managed entity. A business partner is globally uniquely identifiable by a CDL ID, and all managed information such as addresses, documents, and hierarchies is linked to a business partner.

legalEntityobject(DataBlock)

A data block is a collection of data elements that are logically grouped together. Enables you to retrieve data on a specific entity or category.

statusstring

status:

  • OK - Service returned a correct response
  • FAILED - Call to external service failed
  • INVALID_INPUT - Given input parameter is invalid or entry not found
  • AUTHORIZATION_FAILED - Authorization to external service does not succeed
  • EXTERNAL_QUOTA_EXCEEDED - External service quota is exceeded. Not applies to CDQ quota.
Example: "OK"
messagestring

Message providing additional information about the status of the D&B fetch.

Example: "Service returned a correct response"
relationsArray of strings(BranchRelation)

Contains relations with branch companies, only present when using tradeUp option.

Example: ["123456789"]
Response
{
  "cmpelkV2": {
    "transactionDetail": { … },
    "inquiryDetail": { … },
    "organization": { … }
  },
  "dataBlock": {
    "transactionDetail": { … },
    "inquiryDetail": { … },
    "blockStatus": [ … ],
    "organization": { … }
  },
  "lnkeli": {
    "transactionDetail": { … },
    "inquiryDetail": { … },
    "organization": { … }
  },
  "commercialUltimate": {
    "duns": "804735132",
    "primaryName": "Acme Corporation",
    "primaryAddress": { … },
    "path": [ … ],
    "cmpelkV2": { … },
    "dataBlock": { … }
  },
  "cdqRecord": {
    "names": [ … ],
    "legalForm": { … },
    "identifiers": [ … ],
    "categories": [ … ],
    "status": { … },
    "addresses": [ … ],
    "externalId": "The ID managed in the customer's SAP systems.",
    "profile": { … },
    "formattedSapRecord": { … },
    "relations": [ … ],
    "bankAccounts": [ … ],
    "types": [ … ],
    "externalContext": { … }
  },
  "cdqCommercialUltimate": {
    "names": [ … ],
    "legalForm": { … },
    "identifiers": [ … ],
    "categories": [ … ],
    "status": { … },
    "addresses": [ … ],
    "externalId": "The ID managed in the customer's SAP systems.",
    "profile": { … },
    "formattedSapRecord": { … },
    "relations": [ … ],
    "bankAccounts": [ … ],
    "types": [ … ],
    "externalContext": { … }
  },
  "legalEntity": {
    "transactionDetail": { … },
    "inquiryDetail": { … },
    "blockStatus": [ … ],
    "organization": { … }
  },
  "status": "OK",
  "message": "Service returned a correct response",
  "relations": [
    "123456789"
  ]
}

Addresses

Everything about Addresses

Analytics

Everything about reference data analytics

Configurations

Operations

Configuration

Operations

Processing Logs

Operations

Batch Lookup

Operations