Skip to content

Data Exchange API (5)

This API provides services to upload, manipulate and download businesspartner data in the CDL Cloud.

Overview
URL

https://www.cdq.ch/team

Michal Malinka

michal.malinka@cdq.ch

Languages
Servers
Mock server

https://idp.cdq.com/_mock/apis/data-exchange-api/api-v5/

Production SOAP

https://api.corporate-data-league.ch/data-exchange/soap/v5/

Production

https://api.corporate-data-league.ch/data-exchange/

Seed Updates

Manages operations such as creating, updating, or transforming Business Partner data to ensure that the information is current and accurate.

Operations

Analytics

Provides functionalities for analyzing and processing Business Partner data, enabling users to gain insights and perform various analytical operations on the data.

Business Partner Storages

Provides functionalities for creating, retrieving, updating and deleting Business Partner storage, as well as managing associated data sources and data monitors.

Operations

Business Partners

Provides functionalities for creating, retrieving, updating, and deleting Business Partner records, as well as performing various operations such as lookup and upsert.

Operations

List Business Partners Updates

Request

The Read Business Partner Updates endpoint provides an updated Business Partner structure and comprehensive Business Partner information from the Reference Data Sources. By default, only the latest version of a Business Partner from a single data source is provided. However, it's possible to access all historical updates (up to 3 months) by enabling the FeaturesOn: FETCH_HISTORICAL_UPDATES option.

Filtration

A list of updated Business Partners can be filtered in various ways, with tags being the most powerful and important. Tags combine concepts (e.g., NAME_LOCAL, IDENTIFIER, LOCALITY) with actions (e.g., ADDED, MODIFIED). There are two types of classification filters:

  1. summaryClassification: This filter provides Business Partners with a summary classification, which is determined by the highest classificationlevel among all Business Partner concepts.
  2. conceptClassification: This filter indicates the classification of a specific concept of the Business Partner (e.g., name, street, legal form).

Filtration by tag and conceptClassification works in pairs and identifies Business Partners where, for example, the LOCAL_NAME was MODIFIED and this change was classified as MAJOR. When filtering by tag and summaryClassification, the endpoint returns all Business Partners where the specified tags were added to the summary and the general summary classification is, for example, IDENTIFIER_ADDED, + highest classification for all updates =MINOR. Additional filtering options include country, provenance, and external IDs. Providing the data source (or your mirror) in the request can enhance response speed. It's possible to check the total number of updates using featuresOn NUMBER_OF_TOTAL, but can slow down the response.

Recommendations

We recommend periodically reading all Business Partners (at least once) to improve the efficiency of specific filtrations.

Security
basicAuth
Path
storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Query
startAfterstring

Only items with an ID greater than the given one will be retrieved.

When nextStartAfter provided in the response, should be used instead of the ID as an indicator for a next page.

Example: startAfter=5712566172571652
limitinteger(int32)>= 1

Number of items to be returned on the page.

Default 500
Example: limit=100
businessPartnerIdsArray of strings(BusinessPartnerId)<= 100 items

Only show updates for listed Business Partner IDs. When providing list of Business Partner IDs, limit is ignored to provide full page.

Example: businessPartnerIds=63e635235c06b7396330fe40
externalIdsArray of strings(BusinessPartnerExternalId)<= 100 items

Filter updates by Business Partner externalId, limit is ignored to provide full page. When used with the businessPartnerIds parameter, only business partners that have one of the specified externalIds AND one of the specified businessPartnerIds will be returned.

Example: externalIds=The ID managed in the customer's SAP systems.
provenanceTechnicalKeysArray of strings(ProvenanceTechnicalKey)

Show updates for selected provenances by technical keys.

Example: provenanceTechnicalKeys=VIES
exceptProvenanceTechnicalKeysArray of strings(ProvenanceTechnicalKey)

Show updates for all provenances except provided by technical keys. By default, includes ORGANIZATION if not present on provenanceTechnicalKeys list.

Example: exceptProvenanceTechnicalKeys=VIES
dataTransformationDefinitionIdstring(DataTransformationDefinitionId)

When dataTransformationDefinitionId is provided, map updatedBusinessPartner using that transformation.

Example: dataTransformationDefinitionId=SAP.ODM
fromstring

Only show updates which have been modified after this date (ISO 8601). Default is to show the 'last seven days' and farthest in the past is 'since three month'.

Example: from=2019-12-31T16:47
dataSourcesArray of strings(BusinessPartnerDataSource)

Filter by data sources (name or id).

Example: dataSources="CUSTOM_DATA_SOURCE" or "648824a691d8d2503d65103e"
countryShortNamesArray of strings(CountryShortName)

Filter by countries.

Example: countryShortNames=CH
summaryClassificationsArray of strings(UpdateClassificationTechnicalKeyEnum)

Filter by provided summary classifications (logical OR).

Items Enum ValueDescription
CRITICAL

Critical

REJECTED

Update has been rejected

MAJOR

Major change

MINOR

Minor update

TRIVIAL

Trivial update

CONFIRMED

Contents have been confirmed by a data source and not changed

UNCHANGED

Contents have been not changed

Example: summaryClassifications=MAJOR
updateTagsArray of strings(UpdateTagEnum)

Filter by update summary tags.

Items Enum"BANKRUPTCY_BUSINESS_PARTNER""BUSINESS_PARTNER_CATEGORY_ADDED""BUSINESS_PARTNER_CATEGORY_MODIFIED""BUSINESS_PARTNER_CLASSIFICATION_ADDED""BUSINESS_PARTNER_CLASSIFICATION_MODIFIED""BUSINESS_PARTNER_STATUS_ADDED""BUSINESS_PARTNER_STATUS_MODIFIED""BUSINESS_PARTNER_TYPE_ADDED""BUSINESS_PARTNER_TYPE_MODIFIED""DIRECT_LEGAL_RELATION_ADDED"
Example: updateTags=IDENTIFIER_ADDED
updateTagsProfilesArray of strings(UpdateTagsProfileEnum)

Profiled filter by update summary tags.

Items Enum"ADDRESS_DATA""LEGAL_DATA""RELATIONS""VAT_DATA"
Example: updateTagsProfiles=LEGAL_DATA
conceptClassificationsArray of strings(UpdateClassificationTechnicalKeyEnum)

Filter by provided concept classifications (logical OR). When used with the updateTags parameter, only those updates are presented, that match together with respective tag.

Items Enum ValueDescription
CRITICAL

Critical

REJECTED

Update has been rejected

MAJOR

Major change

MINOR

Minor update

TRIVIAL

Trivial update

CONFIRMED

Contents have been confirmed by a data source and not changed

UNCHANGED

Contents have been not changed

Example: conceptClassifications=MAJOR
featuresOnArray of strings(BusinessPartnerUpdatesFeatureParam)

Features to be used during the read Business Partner updates:

  • APPLY_CURATION_DECISIONS - Applies curation decisions from Decision Log to Business Partners in $.values[*].storageBusinessPartner if any decisions found. Requires FETCH_STORAGE_BUSINESS_PARTNER feature. By default, deactivated.
  • FETCH_HISTORICAL_UPDATES - Include historical updates into results. By default, deactivated.
  • FETCH_STORAGE_BUSINESS_PARTNER - Fetch Business Partner from a storage and set in $.values[*].storageBusinessPartner. By default, deactivated.
  • NUMBER_OF_TOTAL - Allows to switch fetching the total number of records to improve performance. By default, deactivated.
Items Enum"APPLY_CURATION_DECISIONS""FETCH_HISTORICAL_UPDATES""FETCH_STORAGE_BUSINESS_PARTNER""NUMBER_OF_TOTAL"
Example: featuresOn=FETCH_STORAGE_BUSINESS_PARTNER
featuresOffArray of strings(BusinessPartnerUpdatesFeatureParam)

Features to be used during the read Business Partner updates:

  • APPLY_CURATION_DECISIONS - Applies curation decisions from Decision Log to Business Partners in $.values[*].storageBusinessPartner if any decisions found. Requires FETCH_STORAGE_BUSINESS_PARTNER feature. By default, deactivated.
  • FETCH_HISTORICAL_UPDATES - Include historical updates into results. By default, deactivated.
  • FETCH_STORAGE_BUSINESS_PARTNER - Fetch Business Partner from a storage and set in $.values[*].storageBusinessPartner. By default, deactivated.
  • NUMBER_OF_TOTAL - Allows to switch fetching the total number of records to improve performance. By default, deactivated.
Items Enum"APPLY_CURATION_DECISIONS""FETCH_HISTORICAL_UPDATES""FETCH_STORAGE_BUSINESS_PARTNER""NUMBER_OF_TOTAL"
Example: featuresOff=FETCH_STORAGE_BUSINESS_PARTNER
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-exchange-api/api-v5/public/v5/storages/72d6900fce6b326088f5d9d91049e3e6/businesspartners/updates

Responses

OK

Bodyapplication/json
limitinteger(Limit)

Number of items per page.

Example: "100"
totalinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
nextStartAfterstring

Available only when you used USE_NEXT_START_AFTER feature. Provides a value to be used as a startAfter in next page request.

Example: "5712566172571652"
valuesArray of objects(BusinessPartnerUpdate)

List of Business Partner Updates.

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

Delete Business Partners

Request

Delete batches of Business Partners by ID or a combination of DataSource and External ID. Maximum of 1000 Business Partners are allowed per batch. In case only a data source is provided in the request, all Business Partners related to this data source will be deleted, but the data source itself will not be deleted.

Security
basicAuth
Path
storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired

cmd

dataSourcestring(BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
businessPartnersArray of objects<= 1000 items

List of Business Partners to be deleted.

featuresOnArray of strings(DeleteFeatureParam)

List of features to be used during delete.

Items Enum ValueDescription
DELETE_BY_EXTERNAL_ID

Deletion is done by external ID.

DELETE_BUSINESS_PARTNER_DATA

Deletion of Business Partner data.

DELETE_LINKS

Deletion of links.

Example: ["DELETE_BY_EXTERNAL_ID"]
featuresOffArray of strings(DeleteFeatureParam)

List of features to be deactivated during delete.

Items Enum ValueDescription
DELETE_BY_EXTERNAL_ID

Deletion is done by external ID.

DELETE_BUSINESS_PARTNER_DATA

Deletion of Business Partner data.

DELETE_LINKS

Deletion of links.

Example: ["DELETE_BY_EXTERNAL_ID"]
profilestring(ProfileTypeParam)

Profile type to be set during to delete.

Enum ValueDescription
STANDARD

Standard profile to be used during delete.

FEATURES_OFF

All features are deactivated.

Example: "STANDARD"
curl -i -X POST \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-exchange-api/api-v5/public/storages/72d6900fce6b326088f5d9d91049e3e6/businesspartners/delete \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "dataSource": "YOUR_DATASOURCE_ID",
    "businessPartners": [
      {
        "externalId": "BP_EXTERNAL_ID"
      }
    ],
    "featuresOn": [
      "DELETE_BY_EXTERNAL_ID"
    ]
  }'

Responses

OK

Bodyapplication/json
numberOfDeletesinteger(NumberOfDeletes)

Number of deleted Business Partners.

Example: "50"
numberOfFailuresinteger(NumberOfFailures)

Number of failures during deletion.

Example: "0"
failuresArray of objects(DeleteFailureLog)

List of failures.

Response
application/json
{
  "numberOfDeletes": "50",
  "numberOfFailures": "0",
  "failures": [
    { … }
  ]
}

Toggle Business Partners Update Monitoring

Request

To toggle update monitoring on multiple BusinessPartners, the permission can be changed via a list of Business Partners, identified by their ID.

After the job is finished, the following actions are taken for Business Partners which match the businessPartnerIds criteria:

  • businessPartner.updateMonitoring fields takes a value of ToggleUpdateMonitoringJobRequest#enable
  • if enable is true then:
  • if enable is false then:
    • all existing links of a Business Partner to Business Partners in non-commercial reference data sources are removed
    • updates are no more propagated for this Business Partner
    • linkage is not performed for any non-commercial reference data source

For toggling a complete Data Source or for a certain Country of a Data Source, please go to Start Toggle Update Monitoring Job.

Security
basicAuth
Path
storageIdstring(BusinessPartnerStorageId)required

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired
enableboolean(ToggleUpdateMonitoringRequestEnable)required

Parameter to describe if the Business Partners should be activated for update monitoring (true) or deactivated (false) for non-commercial reference data sources.

Example: "true"
businessPartnerIdsArray of strings(BusinessPartnerId)[ 1 .. 1000 ] itemsrequired

List of Business Partner IDs to identify all those Business Partners that should be activated/deactivated.

Example: ["63e635235c06b7396330fe40"]
curl -i -X PUT \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-exchange-api/api-v5/public/storages/72d6900fce6b326088f5d9d91049e3e6/businesspartners/toggleUpdateMonitoring \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "enable": "true",
    "businessPartnerIds": [
      "63e635235c06b7396330fe40"
    ]
  }'

Responses

OK

Data Import

Provides functionalities for uploading external data and enabling users to enhance and update their Business Partner records with new information.

Operations

Data Mapping

Provides functionalities for defining and managing data mappings, enabling users to transform and map raw data into structured formats suitable for processing and analysis.

Operations

Data Monitors

Provides functionalities for creating, retrieving, updating and deleting data monitors.

Operations

Data Transformation

Provides functionalities for converting raw data into structured formats.

Operations

DNB Storages

Provides functionalities for creating, retrieving, updating and deleting DNB storage, as well as managing associated data sources and data monitors.

Operations

Files

Provides functionalities for uploading, downloading and deleting files.

Operations

Subscriptions

Provides functionalities for managing subscriptions.

Operations

Data Mappers

Provides functionalities for transforming raw data into structured Business Partner data using predefined data mapper definitions. This allows users to convert various data formats into a standardized format suitable for processing and analysis.

Operations

Relations

Manages relationships between Business Partners.

Operations

Update Classification

Operations

Event Stores

Operations

Business Partner Storages (None Public)

Operations

Restart Monitor Job

Operations

Cache

Operations

Configuration

Operations

Event Store

Operations

CDQ Community Pool

Operations