Bulk Lookup

Business Partners

Everything about Business Partners

Operations

Analytics

Everything about reference data analytics

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 Value	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 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 Value	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 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

Referencedata API (4)

Business Partners

Analytics

Registrations

Addresses

Bulk Fetch

Bulk Lookup

Create Bulk Lookup

Request

Responses

Share the feedback!

Read Bulk Lookup

Request

Responses

Share the feedback!

Cancel Bulk

Batch Lookup

Configurations

Configuration

Referencedata API (4)

Business Partners

Analytics

Registrations

Addresses

Bulk Fetch

Bulk Lookup

Create Bulk Lookup

RequestExpand all

Responses

Share the feedback!

Read Bulk Lookup

Request

Responses

Share the feedback!

Cancel Bulk

Batch Lookup

Configurations

Configuration

Request