Skip to content

Referencedata API (4)

This API provides services to search and read reference data

Download OpenAPI description
Languages
Servers
Production

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

Business Partners

Everything about Business Partners

Operations

Analytics

Everything about reference data analytics

Registrations

Registrations

Addresses

Everything about Addresses

Bulk Fetch

Operations

Bulk Lookup

Operations

Create Bulk Lookup

Request

Create a bulk to lookup multiple business partners at a time.

Security
apiKey
Bodyapplication/jsonrequired
limitinteger(LookupConfigurationLimit)[ 0 .. 1000 ]

Number of items per page. Default value is 10.

Example: "10"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
dataSourcesArray of strings

Filter data sources used during lookup.

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

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

Example: "0.5"
maxCandidatesinteger(LookupConfigurationMaxCandidates)[ 20 .. 200 ]

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

Example: "50"
storagesDataSourcesArray of objects(StoragesDataSource)

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"]
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"
tasksArray of objects(BusinessPartnerLookupTask)[ 1 .. 1000 ] itemsrequired

List of tasks to be executed.

tasks[].​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.

tasks[].​idstring(TaskId)

Unique identifier for a task.

Example: "dc172630-5791-11ee-8c99-0242ac120002"
tasks[].​externalIdstring(TaskExternalId)

Unique identifier provided by a customer to identify a task.

Example: "id-customer-123"
curl -i -X POST \
  https://api.cdq.com/referencedata/rest/v4/businesspartners/lookup/bulks \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "featuresOn": [
      "SHOW_DEBUG_INFO"
    ],
    "tasks": [
      {
        "id": "42010AEF0CEB1EEEACF7ECD80452F903__-/-",
        "businessPartner": {
          "jsonRecord": {
            "addressData": [
              {
                "organizationPostalAddress": {
                  "country": {
                    "code": "DE"
                  },
                  "postCode": "69190",
                  "houseNumber": "16",
                  "street": {
                    "name": "Dietmar-Hopp-Allee"
                  },
                  "primaryRegion": {
                    "code": "08"
                  },
                  "town": {
                    "name": "Walldorf"
                  }
                }
              }
            ],
            "businessPartnerType": "organization",
            "identifications": [
              {
                "identificationType": {
                  "code": "BUP002"
                },
                "identificationNumber": "HRB 719915",
                "entryDateVc": "-",
                "country": {
                  "code": "DE"
                },
                "institute": "Local Court Mannheim",
                "validFrom": "2024-01-15",
                "validTo": "9999-12-31"
              },
              {
                "identificationType": {
                  "code": "DPI001"
                },
                "identificationNumber": "GR.LEI:529900PM64WH8AF1E917HQ",
                "entryDateVc": "-",
                "validFrom": "2024-01-15",
                "validTo": "9999-12-31"
              }
            ],
            "organization": {
              "nameDetails": {
                "formattedOrgNameLine1": "SAP SE",
                "formattedOrgName": "SAP SE"
              }
            },
            "taxNumbers": [
              {
                "taxNumberType": {
                  "code": "DE0"
                },
                "taxNumber": "DE143454214"
              }
            ]
          }
        }
      }
    ]
  }'

Responses

OK

Bodyapplication/json
idstring(BulkId)required

Unique identifier for a set of bulk tasks.

Example: "650b12ac-3768-11ee-be56-0242ac120002"
createdAtstring(CreatedAt)required

Date of creation (ISO 8601-compliant).

Example: "2025-08-15T11:08:44Z"
finishedAtstring(FinishedAt)

Date of finish (ISO 8601-compliant).

Example: "2025-08-15T11:08:44Z"
createdBystring(CreatedBy)required

Creator of a resource.

Example: "76248934691294444"
statusobject(Status)required

Details about status or error of a service

status.​codeinteger(HttpStatusCode)required

RFC 7231 status code for this error.

Example: "400"
status.​technicalKeystring(HttpStatusTechnicalKey)required

Technical key describing the status or error

Example: "OK"
status.​detailsArray of objects(StatusDetails)
status.​pathstring(HttpPath)

Requested path which caused this error.

Example: "/v2/businesspartners/lookup"
status.​timestampstring(StatusTimestamp)

ISO 8601 representation of the timestamp.

Example: "2025-08-15T11:08:44Z"
progressinteger(BulkProgress)[ 0 .. 100 ]

Progress (%) of the bulk execution.

Example: "77"
limitinteger(LookupConfigurationLimit)[ 0 .. 1000 ]

Number of items per page. Default value is 10.

Example: "10"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
dataSourcesArray of strings

Filter data sources used during lookup.

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

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

Example: "0.5"
maxCandidatesinteger(LookupConfigurationMaxCandidates)[ 20 .. 200 ]

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

Example: "50"
storagesDataSourcesArray of objects(StoragesDataSource)

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

List of features to be activated.

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

List of features to be deactivated.

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"
resultsArray of objects(BusinessPartnerLookupBulkResult)
nextStartAfterstring(NextStartAfter)

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

Example: "5712566172571652"
Response
application/json
{ "id": "650b12ac-3768-11ee-be56-0242ac120002", "createdAt": "2025-08-15T11:08:44Z", "finishedAt": "2025-08-15T11:08:44Z", "createdBy": "76248934691294444", "status": { "code": "400", "technicalKey": "OK", "details": [], "path": "/v2/businesspartners/lookup", "timestamp": "2025-08-15T11:08:44Z" }, "progress": "77", "limit": "10", "startAfter": "5712566172571652", "dataSources": [ "VIES" ], "matchingThreshold": "0.5", "maxCandidates": "50", "storagesDataSources": [ {} ], "featuresOn": [ "ACTIVATE_DATASOURCE_BVD" ], "featuresOff": [ "ACTIVATE_DATASOURCE_BVD" ], "configurationId": "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4", "results": [ {} ], "nextStartAfter": "5712566172571652" }

Read Bulk Lookup

Request

Read results for lookup bulk.

Security
apiKey
Path
idstringrequired

Unique identifier for a bulk.

Example: cbed7ac6-a97d-4c23-9060-2a88fa660957
Query
limitinteger(int32)[ 1 .. 1000 ]

Number of items to be returned on the page.

Default 100
Example: limit=20
startAfterstring

Pagination cursor which should be filled with nextStartAfter value provided in the previous page read response.

Default "0"
Example: startAfter=16
curl -i -X GET \
  https://api.cdq.com/referencedata/rest/v4/businesspartners/lookup/bulks/cbed7ac6-a97d-4c23-9060-2a88fa660957 \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring(BulkId)required

Unique identifier for a set of bulk tasks.

Example: "650b12ac-3768-11ee-be56-0242ac120002"
createdAtstring(CreatedAt)required

Date of creation (ISO 8601-compliant).

Example: "2025-08-15T11:08:44Z"
finishedAtstring(FinishedAt)

Date of finish (ISO 8601-compliant).

Example: "2025-08-15T11:08:44Z"
createdBystring(CreatedBy)required

Creator of a resource.

Example: "76248934691294444"
statusobject(Status)required

Details about status or error of a service

status.​codeinteger(HttpStatusCode)required

RFC 7231 status code for this error.

Example: "400"
status.​technicalKeystring(HttpStatusTechnicalKey)required

Technical key describing the status or error

Example: "OK"
status.​detailsArray of objects(StatusDetails)
status.​pathstring(HttpPath)

Requested path which caused this error.

Example: "/v2/businesspartners/lookup"
status.​timestampstring(StatusTimestamp)

ISO 8601 representation of the timestamp.

Example: "2025-08-15T11:08:44Z"
progressinteger(BulkProgress)[ 0 .. 100 ]

Progress (%) of the bulk execution.

Example: "77"
limitinteger(LookupConfigurationLimit)[ 0 .. 1000 ]

Number of items per page. Default value is 10.

Example: "10"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
dataSourcesArray of strings

Filter data sources used during lookup.

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

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

Example: "0.5"
maxCandidatesinteger(LookupConfigurationMaxCandidates)[ 20 .. 200 ]

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

Example: "50"
storagesDataSourcesArray of objects(StoragesDataSource)

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

List of features to be activated.

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

List of features to be deactivated.

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"
resultsArray of objects(BusinessPartnerLookupBulkResult)
nextStartAfterstring(NextStartAfter)

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

Example: "5712566172571652"
Response
application/json
{ "id": "650b12ac-3768-11ee-be56-0242ac120002", "createdAt": "2025-08-15T11:08:44Z", "finishedAt": "2025-08-15T11:08:44Z", "createdBy": "76248934691294444", "status": { "code": "400", "technicalKey": "OK", "details": [], "path": "/v2/businesspartners/lookup", "timestamp": "2025-08-15T11:08:44Z" }, "progress": "77", "limit": "10", "startAfter": "5712566172571652", "dataSources": [ "VIES" ], "matchingThreshold": "0.5", "maxCandidates": "50", "storagesDataSources": [ {} ], "featuresOn": [ "ACTIVATE_DATASOURCE_BVD" ], "featuresOff": [ "ACTIVATE_DATASOURCE_BVD" ], "configurationId": "c074b9f3-abf0-4f8e-9a20-74deb6cfa2a4", "results": [ {} ], "nextStartAfter": "5712566172571652" }

Cancel Bulk

Operations

Batch Lookup

Operations

Configurations

Operations

Configuration

Operations