Business Partners

Create Business Partner Tags

Allows the creation of Business Partner tags. The tags are created in the Business Partner profile.

SecurityapiKey
Request
path Parameters
businessPartnerId
required
string (BusinessPartnerStorageId)

Business Partner identifier within a storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
required
Array of objects (TagCreate) <= 30 items

List of Tags.

Responses
200

OK

400

Bad Request

post/v4/storages/{storageId}/businesspartners/{businessPartnerId}/profile/tags
Request samples
application/json
{
  • "tags": [
    ]
}
Response samples
application/json
{
  • "tags": [
    ],
  • "results": [
    ]
}

Delete Business Partner Tags

Allows the deletion of Business Partner tags. The tags are deleted from the Business Partner profile.

SecurityapiKey
Request
path Parameters
businessPartnerId
required
string (BusinessPartnerStorageId)

Business Partner identifier within a storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
required
Array of objects (TagDelete) <= 30 items

List of deleted Tags.

Responses
200

OK

400

Bad Request

post/v4/storages/{storageId}/businesspartners/{businessPartnerId}/profile/tags/delete
Request samples
application/json
{
  • "tags": [
    ]
}
Response samples
application/json
{
  • "tags": [
    ],
  • "results": [
    ]
}

Delete Business PartnersWSDL

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.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required

cmd

Array of objects <= 1000 items

List of Business Partners to be deleted.

dataSource
string (BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
featuresOn
Array of strings (DeleteFeatureParam)

List of features to be used during delete.

Items Enum: "DELETE_BY_EXTERNAL_ID" "DELETE_BUSINESS_PARTNER_DATA" "DELETE_LINKS"
Example: ["DELETE_BY_EXTERNAL_ID"]
Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/storages/{storageId}/businesspartners/delete
Request samples
application/json
{
  • "dataSource": "YOUR_DATASOURCE_ID",
  • "businessPartners": [
    ],
  • "featuresOn": [
    ]
}
Response samples
application/json
{
  • "numberOfDeletes": "50",
  • "numberOfFailures": "0",
  • "failures": [
    ]
}

Fetch a Business Partner

Fetch a Business Partner from this storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
dataSource
string (BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
externalId
required
string (BusinessPartnerExternalIdParam) non-empty

Arbitrary identifier type to mark customer IDs that are "external"\ \ from CDQ's perspective. This is the identifier a customer provides to identify\ \ its records.

Example: "The ID managed in the customer's SAP systems."
featuresOff
Array of strings (FetchBusinessPartnerFeatureParam)

Features to be excluded during the fetch Business Partner.

Items Enum: Description
FETCH_RECORD

Allows to switch fetching record field to reduce data size. By default, turned on.

FETCH_RELATIONS

Allows to switch fetching relations of Business Partners. By default, deactivated. Only for storages with RELATIONS feature activated.

Example: ["FETCH_RECORD"]
featuresOn
Array of strings (FetchBusinessPartnerFeatureParam)

Features to be used during the fetch Business Partner.

Items Enum: Description
FETCH_RECORD

Allows to switch fetching record field to reduce data size. By default, turned on.

FETCH_RELATIONS

Allows to switch fetching relations of Business Partners. By default, deactivated. Only for storages with RELATIONS feature activated.

Example: ["FETCH_RECORD"]
Responses
200

OK

401

Unauthorized

403

Forbidden

post/v4/storages/{storageId}/businesspartners/fetch
Request samples
application/json
{
  • "externalId": "The ID managed in the customer's SAP systems.",
  • "dataSource": "648824a691d8d2503d65103e",
  • "featuresOn": [
    ],
  • "featuresOff": [
    ]
}
Response samples
application/json
{
  • "businessPartner": {
    },
  • "status": "NOT_FOUND",
  • "message": "Business Partner has been fetched successfully."
}

List Business PartnersWSDL

Read a page of business partners from the storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
query Parameters
businessPartnerId
Array of strings (BusinessPartnerId)

Business Partner IDs which should be filtered.

Example: businessPartnerId=63e635235c06b7396330fe40
countryCode
Array of strings (CountryShortName)

Country code (ISO 3166-1 alpha-2) used to filter the result of business partners returned.

Example: countryCode=CH
curationLogResultStatus
Array of strings (CurationLevelParam)

Curation log of curation result.

Items Enum: Description
UNKNOWN

No possibility to determine curation level.

LEVEL_1

The address was not found by the CDQ in the employed external data sources.

LEVEL_2

The address was found, but there were significant changes in critical fields.

LEVEL_3

The address was found and there are minor changes in highly important fields.

LEVEL_4

The address was found by the CDQ. There were only changes in less critical fields such as the address/premise or address/thoroughfare/number.

LEVEL_5

The address was found by the CDQ, but no major changes have been made as the address was correct.

LEVEL_6

The address was found in the shared CDQ data pool. This means another company uses the same address which is a very reliable indicator that the address is correct (only in an alpha version).

Example: curationLogResultStatus=LEVEL_1
dataSource
Array of strings (BusinessPartnerDataSource)

Data Source (name or ID) to be measured during calculating statistics. By default, all Data Sources are measured.

Example: dataSource="CUSTOM_DATA_SOURCE" or "648824a691d8d2503d65103e"
externalId
Array of strings (BusinessPartnerExternalId)

Business Partner externalIDs.

Example: externalId=The ID managed in the customer's SAP systems.
featuresOff
Array of strings (BusinessPartnersReadFeatureParam)

Features to be deactivated.

Items Enum: Description
APPLY_CURATION_DECISIONS

Applies curation decisions from Decision Log to business partner if any decisions found. By default, deactivated.

CURATION_LOG_RESULT_STATUSES

Allows to switch fetching curation log result statuses. By default, deactivated.

FETCH_RECORD

Allows to switch fetching record field to reduce data size. By default, turned on.

FETCH_RELATIONS

Allows to switch fetching relations of Business Partners. By default, deactivated. Only for storages with RELATIONS feature activated.

NUMBER_OF_TOTAL

Allows to switch fetching the total number of Business Partners to improve performance. By default, turned on.

USE_NEXT_START_AFTER

Allows to switch fetching the next page of Business Partners using the nextStartAfter value. By default, deactivated.

VALIDATION_LOG_RESULT_STATUSES

Allows to switch fetching validation log result statuses. By default, deactivated.

Example: featuresOff=APPLY_CURATION_DECISIONS
featuresOn
Array of strings (BusinessPartnersReadFeatureParam)

Features to be activated.

Items Enum: Description
APPLY_CURATION_DECISIONS

Applies curation decisions from Decision Log to business partner if any decisions found. By default, deactivated.

CURATION_LOG_RESULT_STATUSES

Allows to switch fetching curation log result statuses. By default, deactivated.

FETCH_RECORD

Allows to switch fetching record field to reduce data size. By default, turned on.

FETCH_RELATIONS

Allows to switch fetching relations of Business Partners. By default, deactivated. Only for storages with RELATIONS feature activated.

NUMBER_OF_TOTAL

Allows to switch fetching the total number of Business Partners to improve performance. By default, turned on.

USE_NEXT_START_AFTER

Allows to switch fetching the next page of Business Partners using the nextStartAfter value. By default, deactivated.

VALIDATION_LOG_RESULT_STATUSES

Allows to switch fetching validation log result statuses. By default, deactivated.

Example: featuresOn=APPLY_CURATION_DECISIONS
fromJobProcessedAt
string

Returns the results which have one of the log result status -> jobProcessedAt after given date. The given date should support ISO-8601 representation.

Example: fromJobProcessedAt=2024-11-20T14:46:34Z
fromProcessedAt
string

Returns the results which have one of the log result status -> processedAt after given date. The given date should support ISO-8601 representation.

Example: fromProcessedAt=2024-11-20T14:46:34Z
fromTriggerProcessedAt
string

Returns the results which have one of the log result status -> triggerProcessedAt after given date. The given date should support ISO-8601 representation.

Example: fromTriggerProcessedAt=2024-11-20T14:46:34Z
hasRawData
boolean
Default: false

Flag to filter result of business partners based on the existence of the record attribute (raw data).

Example: hasRawData=false
limit
integer <int32> >= 1
Default: 500

Number of items to be returned on the page.

Example: limit=100
logResultTriggerProvenanceTechnicalKeys
Array of strings (ProvenanceTechnicalKey)

Provenance technical keys used for filtering the result which should match with at least one of any log result status -> triggerType fields.

Example: logResultTriggerProvenanceTechnicalKeys=VIES
logResultTriggerType
Array of strings (ProcessingLogResultStatusTriggerTypeTechnicalKeyParam)

Trigger type used for filtering the result which should match with at least one of any log result status -> triggerType fields.

Items Enum: "CREATED" "UPDATED" "REFERENCE_DATA_CHANGED" "REFRESHED" "JOB"
Example: logResultTriggerType=CREATED
modifiedAfter
string

Return entries which were modified after given data. The given date should support ISO-8601 representation.

Example: modifiedAfter=2024-11-20T14:46:34Z
modifiedBefore
string

Return entries which were modified before given data. The given date should support ISO-8601 representation.

Example: modifiedBefore=2024-11-20T14:46:34Z
reviewStatus
string (ReviewStatusParam)

Review status used for filtering the result data.

Enum: Description
REVIEWED

Reviewed.

NOT_REVIEWED

Not reviewed.

Example: reviewStatus=REVIEWED
sharingStatus
Array of strings

Business Partner Sharing Status which should be filtered.

Sharing Statuses which can be filtered out:

  • UNDER_CONSIDERATION
  • UNDISCLOSED_RECORD
  • MISSING_INFORMATION_FOR_LINKAGE
  • ERRONEOUS_INFORMATION_FOR_LINKAGE
  • ERRONEOUS_RECORD
  • PENDING_LINKAGE_DECISION
  • PROCESS_ISSUE
  • SHARED_WITH_NO_MATCH
  • SHARED_WITH_CONFIDENT_MATCH
  • SHARED_WITH_NO_MATCH_BY_REVIEW
  • SHARED_BY_REVIEW
Example: sharingStatus=UNDER_CONSIDERATION
startAfter
string

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
tagTypeTechnicalKey
string (TagTypeTechnicalKey)

Type Technical Key of tags that are provided in 'tagValues' query param.

Example: tagTypeTechnicalKey=WAREHOUSE
tagValues
Array of strings (TagValue)

Tag values that will be used to filter Business Partners. Values are connected with logical 'AND'.

Example: tagValues=Warehouse
toJobProcessedAt
string

Returns the results which have one of the log result status -> jobProcessedAt before given date. The given date should support ISO-8601 representation.

Example: toJobProcessedAt=2024-11-20T14:46:34Z
toProcessedAt
string

Returns the results which have one of the log result status -> processedAt before given date. The given date should support ISO-8601 representation.

Example: toProcessedAt=2024-11-20T14:46:34Z
toTriggerProcessedAt
string

Returns the results which have one of the log result status -> triggerProcessedAt before given date. The given date should support ISO-8601 representation.

Example: toTriggerProcessedAt=2024-11-20T14:46:34Z
typeTechnicalKeys
Array of strings (BusinessPartnerTypeTechnicalKeyParam) <= 1 items

Business Partner type technical keys which should be filtered.

Items Enum: "BP_ADDRESS" "LEGAL_ENTITY" "ORGANIZATIONAL_UNIT" "UNKNOWN" "BRAND"
Example: typeTechnicalKeys=LEGAL_ENTITY
updateMonitoring
boolean

Flag to filter business partners by the value of updateMonitoring attribute.

Example: updateMonitoring=true
validationLogResultStatus
Array of strings (ValidationLevelParam)

Violation level of validation result.

Items Enum: Description
OK

No data quality issues have been found after executing all the rules.

ERROR

At least 1 ERROR defect has been found.

WARNING

At least 1 WARNING defect has been found.

INFO

At least 1 INFO defect has been found.

UNKNOWN

No ERROR has been found, but at least one data quality rule could not be executed.

Example: validationLogResultStatus=WARNING
validationSharingLogResultStatus
Array of strings (ValidationLevelParam)

Violation level of sharing validation result.

Items Enum: Description
OK

No data quality issues have been found after executing all the rules.

ERROR

At least 1 ERROR defect has been found.

WARNING

At least 1 WARNING defect has been found.

INFO

At least 1 INFO defect has been found.

UNKNOWN

No ERROR has been found, but at least one data quality rule could not be executed.

Example: validationSharingLogResultStatus=WARNING
Responses
200

OK

400

Bad Request

401

Unauthorized

get/v4/storages/{storageId}/businesspartners
Request samples 
Response samples 
application/json
{
  • "startAfter": "5712566172571652",
  • "limit": "100",
  • "total": "67",
  • "values": [
    ],
  • "nextStartAfter": "5712566172571652"
}
List Business Partners Updates
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. 

  2. conceptClassification: This filter indicates the classification of a specific concept of the Business Partner (e.g., name, street, legal form).
    3. 



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.


SecurityapiKey 
Request 
path Parameters
storageId
required
string (BusinessPartnerStorageId) 
Unique identifier of the Storage.


 
 Example:  72d6900fce6b326088f5d9d91049e3e6
query Parameters
businessPartnerIds
Array 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
conceptClassifications
Array 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: {"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
countryShortNames
Array of strings (CountryShortName) 
Filter by countries.


 
 Example:  countryShortNames=CH
dataSources
Array of strings (BusinessPartnerDataSource) 
Filter by data sources (name or id).


 
 Example:  dataSources="CUSTOM_DATA_SOURCE" or "648824a691d8d2503d65103e"
dataTransformationDefinitionId
string (DataTransformationDefinitionId) 
When dataTransformationDefinitionId is provided, map updatedBusinessPartner using that transformation.


 
 Example:  dataTransformationDefinitionId=SAP.ODM
exceptProvenanceTechnicalKeys
Array 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
externalIds
Array 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.
featuresOff
Array 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
featuresOn
Array 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
from
string
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=2024-11-20T14:46:34Z
limit
integer <int32>   >= 1 
 Default:  500
Number of items to be returned on the page.


 
 Example:  limit=100
provenanceTechnicalKeys
Array of strings (ProvenanceTechnicalKey) 
Show updates for selected provenances by technical keys.


 
 Example:  provenanceTechnicalKeys=VIES
startAfter
string
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
summaryClassifications
Array of strings (UpdateClassificationTechnicalKeyEnum) 
Filter by provided summary classifications (logical OR).


Items Enum: {"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
updateTags
Array 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" "DIRECT_LEGAL_RELATION_MODIFIED" "DISSOLUTION_BUSINESS_PARTNER" "DOMESTIC_BRANCH_RELATION_ADDED" "DOMESTIC_BRANCH_RELATION_MODIFIED" "DOMESTIC_COMMERCIAL_ULTIMATE_RELATION_ADDED" "DOMESTIC_COMMERCIAL_ULTIMATE_RELATION_MODIFIED" "DOMESTIC_LEGAL_ULTIMATE_RELATION_ADDED" "DOMESTIC_LEGAL_ULTIMATE_RELATION_MODIFIED" "GLOBAL_COMMERCIAL_ULTIMATE_RELATION_ADDED" "GLOBAL_COMMERCIAL_ULTIMATE_RELATION_MODIFIED" "GLOBAL_LEGAL_ULTIMATE_RELATION_ADDED" "GLOBAL_LEGAL_ULTIMATE_RELATION_MODIFIED" "IDENTIFIER_ADDED" "IDENTIFIER_HARMONIZED" "IDENTIFIER_MODIFIED" "IDENTIFIER_STATUS_ADDED" "IDENTIFIER_STATUS_MODIFIED" "IDENTIFIER_VALUE_MODIFIED" "IN_LIQUIDATION_BUSINESS_PARTNER" "INACTIVE_BUSINESS_PARTNER" "INSOLVENCY_BUSINESS_PARTNER" "INTERNAL_RELATION_ADDED" "INTERNAL_RELATION_MODIFIED" "INTERNATIONAL_BRANCH_RELATION_ADDED" "INTERNATIONAL_BRANCH_RELATION_MODIFIED" "LEGAL_FORM_ADDED" "LEGAL_FORM_MODIFIED" "LEI_DIRECT_PARENT_ADDED" "LEI_DIRECT_PARENT_MODIFIED" "LEI_INTERNATIONAL_BRANCH_ADDED" "LEI_INTERNATIONAL_BRANCH_MODIFIED" "LEI_ULTIMATE_PARENT_ADDED" "LEI_ULTIMATE_PARENT_MODIFIED" "LOCAL_ADDRESS_ADDED" "LOCAL_ADDRESS_ADMINISTRATIVE_AREA_ADDED" "LOCAL_ADDRESS_ADMINISTRATIVE_AREA_MODIFIED" "LOCAL_ADDRESS_COUNTRY_ADDED" "LOCAL_ADDRESS_COUNTRY_MODIFIED" "LOCAL_ADDRESS_GEO_COORDINATES_ADDED" "LOCAL_ADDRESS_GEO_COORDINATES_MODIFIED" "LOCAL_ADDRESS_LOCALITY_ADDED" "LOCAL_ADDRESS_LOCALITY_MODIFIED" "LOCAL_ADDRESS_MODIFIED" "LOCAL_ADDRESS_POSTAL_DELIVERY_POINT_ADDED" "LOCAL_ADDRESS_POSTAL_DELIVERY_POINT_MODIFIED" "LOCAL_ADDRESS_POST_CODE_ADDED" "LOCAL_ADDRESS_POST_CODE_MODIFIED" "LOCAL_ADDRESS_PREMISE_ADDED" "LOCAL_ADDRESS_PREMISE_MODIFIED" "LOCAL_ADDRESS_THOROUGHFARE_ADDED" "LOCAL_ADDRESS_THOROUGHFARE_MODIFIED" "LOCAL_NAME_ADDED" "LOCAL_NAME_MODIFIED" "OTHER_NAME_ADDED" "OTHER_NAME_MODIFIED" "POST_CODE_HARMONIZED" "LEGAL_ADDRESS_ADDED" "LEGAL_ADDRESS_ADMINISTRATIVE_AREA_ADDED" "LEGAL_ADDRESS_ADMINISTRATIVE_AREA_MODIFIED" "LEGAL_ADDRESS_COUNTRY_ADDED" "LEGAL_ADDRESS_COUNTRY_MODIFIED" "LEGAL_ADDRESS_GEO_COORDINATES_ADDED" "LEGAL_ADDRESS_GEO_COORDINATES_MODIFIED" "LEGAL_ADDRESS_LOCALITY_ADDED" "LEGAL_ADDRESS_LOCALITY_MODIFIED" "LEGAL_ADDRESS_MODIFIED" "LEGAL_ADDRESS_POSTAL_DELIVERY_POINT_ADDED" "LEGAL_ADDRESS_POSTAL_DELIVERY_POINT_MODIFIED" "LEGAL_ADDRESS_POST_CODE_ADDED" "LEGAL_ADDRESS_POST_CODE_MODIFIED" "LEGAL_ADDRESS_PREMISE_ADDED" "LEGAL_ADDRESS_PREMISE_MODIFIED" "LEGAL_ADDRESS_THOROUGHFARE_ADDED" "LEGAL_ADDRESS_THOROUGHFARE_MODIFIED" "LEGAL_NAME_ADDED" "LEGAL_NAME_MODIFIED" "RESTRUCTURING_BUSINESS_PARTNER" "RELATION_ADDED" "RELATION_MODIFIED" "SEED_UPDATE" "UPDATE_PROPOSAL_INDICATOR" "VAT_PAYER_STATUS_ADDED" "VAT_PAYER_STATUS_MODIFIED" "VAT_REGISTERED_ADDRESS_ADDED" "VAT_REGISTERED_ADDRESS_ADMINISTRATIVE_AREA_ADDED" "VAT_REGISTERED_ADDRESS_ADMINISTRATIVE_AREA_MODIFIED" "VAT_REGISTERED_ADDRESS_COUNTRY_ADDED" "VAT_REGISTERED_ADDRESS_COUNTRY_MODIFIED" "VAT_REGISTERED_ADDRESS_GEO_COORDINATES_ADDED" "VAT_REGISTERED_ADDRESS_GEO_COORDINATES_MODIFIED" "VAT_REGISTERED_ADDRESS_LOCALITY_ADDED" "VAT_REGISTERED_ADDRESS_LOCALITY_MODIFIED" "VAT_REGISTERED_ADDRESS_MODIFIED" "VAT_REGISTERED_ADDRESS_POSTAL_DELIVERY_POINT_ADDED" "VAT_REGISTERED_ADDRESS_POSTAL_DELIVERY_POINT_MODIFIED" "VAT_REGISTERED_ADDRESS_POST_CODE_ADDED" "VAT_REGISTERED_ADDRESS_POST_CODE_MODIFIED" "VAT_REGISTERED_ADDRESS_PREMISE_ADDED" "VAT_REGISTERED_ADDRESS_PREMISE_MODIFIED" "VAT_REGISTERED_ADDRESS_THOROUGHFARE_ADDED" "VAT_REGISTERED_ADDRESS_THOROUGHFARE_MODIFIED" "VAT_REGISTERED_NAME_ADDED" "VAT_REGISTERED_NAME_MODIFIED" "VALUE_MODIFIED"  
 Example:  updateTags=IDENTIFIER_ADDED
updateTagsProfiles
Array of strings (UpdateTagsProfileEnum) 
Profiled filter by update summary tags.


Items Enum: "ADDRESS_DATA" "LEGAL_DATA" "RELATIONS" "VAT_DATA"  
 Example:  updateTagsProfiles=LEGAL_DATA
Responses 
200
OK


400
Bad Request


get/v5/storages/{storageId}/businesspartners/updates
Request samples 
Response samples 
application/json
{
  • "limit": "100",
  • "total": "67",
  • "startAfter": "5712566172571652",
  • "nextStartAfter": "5712566172571652",
  • "values": [
    ]
}
Lookup a Business PartnerWSDL
Lookup a Business Partner in provided storage.


SecurityapiKey 
Request 
path Parameters
storageId
required
string (BusinessPartnerStorageId) 
Unique identifier of the Storage.


 
 Example:  72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
cmd


object (BusinessPartnerLookupParam) 
Lookup business partner data in connected data sources like the CDQ Community Data Pool, Business registers, or even in the own data mirror.


 
dataSources
Array of strings
List of Data Sources.


 
 Example:  ["\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\""]
featuresOff
Array of strings (FetchBusinessPartnerFeatureParam) 
Features to be excluded during the fetch Business Partner.


Items Enum: Description
FETCH_RECORD
Allows to switch fetching record field to reduce data size. By default, turned on.


FETCH_RELATIONS
Allows to switch fetching relations of Business Partners. By default, deactivated. Only for storages with RELATIONS feature activated.


 
 Example:  ["FETCH_RECORD"]
featuresOn
Array of strings (FetchBusinessPartnerFeatureParam) 
Features to be used during the fetch Business Partner.


Items Enum: Description
FETCH_RECORD
Allows to switch fetching record field to reduce data size. By default, turned on.


FETCH_RELATIONS
Allows to switch fetching relations of Business Partners. By default, deactivated. Only for storages with RELATIONS feature activated.


 
 Example:  ["FETCH_RECORD"]
matchingThreshold
number <double>  (DataMatchingThreshold)   [ 0 .. 1 ] 
 Default:  0
The threshold for the data matching.


 
 Example:  "0.5"
page
integer (Page)   >= 0 
 Default:  0
Current page number.


 
 Example:  "1"
pageSize
integer (PageSize)   [ 1 .. 1000 ] 
 Default:  10
Number of items per page.


 
 Example:  "100"
Responses 
200
OK


401
Unauthorized


403
Forbidden


404
Not Found


post/v4/storages/{storageId}/businesspartners/lookup
Request samples 
application/json
{
  • "matchingThreshold": "0.5",
  • "pageSize": "100",
  • "page": "1",
  • "dataSources": [
    ],
  • "businessPartner": {
    },
  • "featuresOn": [
    ],
  • "featuresOff": [
    ]
}
Response samples 
application/json
{
  • "pageSize": "100",
  • "total": "67",
  • "page": "1",
  • "values": [
    ],
  • "debugInfo": {
    }
}
Poll a Toggle Update Monitoring Job
Poll endpoint for a job created in POST toggleUpdateMonitoringJobs.


SecurityapiKey 
Request 
path Parameters
jobId
required
string (JobId) 
Unique identifier of a job.


 
 Example:  35f23c03-1c22-45fe-9484-3ffe769325de
Responses 
200
OK


get/jobs/toggleUpdateMonitoringJobs/{jobId}
Request samples 
Response samples 
application/json
{
  • "job": {
    },
  • "status": "OK"
}
Random Business PartnersDeprecated
Get random Business Partners from this storage.


SecurityapiKey 
Request 
path Parameters
storageId
required
string (BusinessPartnerStorageId) 
Unique identifier of the Storage.


 
 Example:  72d6900fce6b326088f5d9d91049e3e6
query Parameters
countryCode
string (CountryShortName) 
Country code (ISO 3166-1 alpha-2) used to filter the result of business partners returned.


 
 Example:  countryCode=CH
dataSource
string (BusinessPartnerDataSource) 
Data Source (name or ID) to be measured during calculating statistics. By default, all Data Sources are measured.


 
 Example:  dataSource="CUSTOM_DATA_SOURCE" or "648824a691d8d2503d65103e"
featureOff
Array of strings (FetchBusinessPartnerFeatureParam) 
Features to be excluded during the fetch Business Partner.


Items Enum: Description
FETCH_RECORD
Allows to switch fetching record field to reduce data size. By default, turned on.


FETCH_RELATIONS
Allows to switch fetching relations of Business Partners. By default, deactivated. Only for storages with RELATIONS feature activated.


 
 Example:  featureOff=FETCH_RECORD
featureOn
Array of strings (FetchBusinessPartnerFeatureParam) 
Features to be used during the fetch Business Partner.


Items Enum: Description
FETCH_RECORD
Allows to switch fetching record field to reduce data size. By default, turned on.


FETCH_RELATIONS
Allows to switch fetching relations of Business Partners. By default, deactivated. Only for storages with RELATIONS feature activated.


 
 Example:  featureOn=FETCH_RECORD
limit
integer <int32>   [ 1 .. 10 ] 
 Default:  1
Number of items to be returned on the page.


 
 Example:  limit=5
modifiedAfter
string
Return entries which were modified after given data. The given date should support ISO-8601 representation.


 
 Example:  modifiedAfter=2024-11-20T14:46:34Z
modifiedBefore
string
Return entries which were modified before given data. The given date should support ISO-8601 representation.


 
 Example:  modifiedBefore=2024-11-20T14:46:34Z
Responses 
200
OK


401
Unauthorized


403
Forbidden


get/v4/storages/{storageId}/businesspartners/random
Request samples 
Response samples 
application/json
{
  • "limit": "100",
  • "values": [
    ]
}
Read a Business Partner
Read Business Partner by ID.


SecurityapiKey 
Request 
path Parameters
id
required
string (BusinessPartnerId) 
Unique identifier of the Business Partner.


 
 Example:  63e635235c06b7396330fe40
storageId
required
string (BusinessPartnerStorageId) 
Unique identifier of the Storage.


 
 Example:  72d6900fce6b326088f5d9d91049e3e6
query Parameters
featureOff
Array of strings (ReadBusinessPartnerFeatureParam) 
Features to be deactivated during the read Business Partner.


Items Enum: "APPLY_CURATION_DECISIONS" "FETCH_RECORD" "FETCH_RELATIONS"  
 Example:  featureOff=FETCH_RECORD
featureOn
Array of strings (ReadBusinessPartnerFeatureParam) 
Features to be used during the read Business Partner.


Items Enum: "APPLY_CURATION_DECISIONS" "FETCH_RECORD" "FETCH_RELATIONS"  
 Example:  featureOn=FETCH_RECORD
Responses 
200
OK


get/v4/storages/{storageId}/businesspartners/{id}
Request samples 
Response samples 
application/json
{
  • "id": "63e635235c06b7396330fe40",
  • "createdAt": "2024-11-20T14:46:34Z",
  • "modifiedAt": "2024-11-20T14:46:34Z",
  • "externalId": "The ID managed in the customer's SAP systems.",
  • "dataSource": "\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\"",
  • "disclosed": "false",
  • "updateMonitoring": "true",
  • "updateCommercialMonitoring": [
    ],
  • "metadata": {
    },
  • "record": "{\"name\": \"BUSINESSPARTNER_NAME\", ...}",
  • "names": [],
  • "legalForm": {},
  • "identifiers": [],
  • "categories": [],
  • "status": {},
  • "profile": {},
  • "relations": [
    ],
  • "types": [],
  • "addresses": [
    ],
  • "bankAccounts": [
    ],
  • "externalContext": {
    }
}
Start a Toggle Update Monitoring Job
To toggle update monitoring on multiple BusinessPartners, the permission can be changed in two ways:


    

  1. A complete Data Source identified by the parameter 'dataSourceId'
    2. 

  2. Or for a certain Country of a Data Source. This requires both parameters 'dataSourceId' and 'countryShortName' to be set
    3. 



After the job is finished, the following actions are taken for Business Partners which match the dataSourceId and countryShortName 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 via a list of Business Partners, identified by their ID, please go to Toggle Update Monitoring of Business Partners.


SecurityapiKey 
Request 
Request Body schema: application/json
required
countryShortName
string (CountryShortName) 
Country code (ISO 3166-1 alpha-2).


 
 Example:  "CH"
dataSourceId
required
string (BusinessPartnerStorageDataSourceId) 
Unique identifier for a Data Source of the Storage.


 
 Example:  "648824a691d8d2503d65103e"
description
string (JobDescription) 
Detailed description of a Job.


 
 Example:  "I started this job to improve quality of our data."
enable
required
boolean (ToggleUpdateMonitoringRequestEnable) 
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"
name
string (JobName) 
Name of a Job.


 
 Example:  "Process vendor data."
storageId
required
string (BusinessPartnerStorageId) 
Unique identifier of the Storage.


 
 Example:  "72d6900fce6b326088f5d9d91049e3e6"
Responses 
200
OK


400
The sent request is malformed.


post/jobs/toggleUpdateMonitoringJobs
Request samples 
application/json
{
  • "enable": "true",
  • "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  • "name": "Process vendor data.",
  • "description": "I started this job to improve quality of our data.",
  • "dataSourceId": "648824a691d8d2503d65103e",
  • "countryShortName": "CH"
}
Response samples 
application/json
{
  • "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  • "createdBy": "76248934691294444",
  • "createdAt": "2024-11-20T14:46:34Z",
  • "modifiedAt": "2024-11-20T14:46:34Z",
  • "progress": "77",
  • "status": "RUNNING",
  • "statusMessage": "The job failed because storage is empty.",
  • "enable": "true",
  • "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  • "dataSourceId": "648824a691d8d2503d65103e",
  • "countryShortName": "CH"
}
Toggle Business Partners Update Monitoring
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.


SecurityapiKey 
Request 
path Parameters
storageId
required
string (BusinessPartnerStorageId) 
Unique identifier of the Storage.


 
 Example:  72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
businessPartnerIds
required
Array of strings (BusinessPartnerId)   [ 1 .. 1000 ] items 
List of Business Partner IDs to identify all those Business Partners that should be activated/deactivated.


 
 Example:  ["63e635235c06b7396330fe40"]
enable
required
boolean (ToggleUpdateMonitoringRequestEnable) 
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"
Responses 
204
OK


put/storages/{storageId}/businesspartners/toggleUpdateMonitoring
Request samples 
application/json
{
  • "enable": "true",
  • "businessPartnerIds": [
    ]
}
Update Disclosure
To un-/disclose multiple BusinessPartners, the disclosure can be changed in three ways:


    

  1. A complete data source identified by the parameter 'dataSourceId' (deprecated - use Sharing Scopes instead. Still applicable, but can be overwritten by Sharing Scopes)
    2. 

  2. Or for a certain country of a data source. This requires both parameters 'dataSourceId' and 'countryCode' to be set (deprecated - use Sharing Scopes instead. Still applicable, but can be overwritten by Sharing Scopes)
    3. 

  3. Or a list of Business Partners, identified by their ID. The other parameters should be left empty. Note: disclosure set via Business Partner ID can be overwritten by creation or deletion of a Sharing Scope.
    4. 



Any other combination may result in a Bad Request.


For more details, you can read about Sharing Scopes.


SecurityapiKey 
Request 
path Parameters
storageId
required
string (BusinessPartnerStorageId) 
Unique identifier of the Storage.


 
 Example:  72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
businessPartnerIds
Array of strings (BusinessPartnerId)   non-empty 
List of BusinessPartner IDs to identify all those BusinessPartners that should be un-/disclose.


 
 Example:  ["63e635235c06b7396330fe40"]
countryCode
string
 Deprecated 
A country code (ISO 3166-2), to be used in combination with a DataSource ID to un-/disclose all matching BusinessPartners.


 
 Example:  "DE"
dataSourceId
string
 Deprecated 
A DataSource ID for which all related BusinessPartners should be un-/disclose.


 
 Example:  "648824a691d8d2503d65103e"
disclosed
required
boolean
Parameter to describe if the BusinessPartners should be disclosed (true) or undisclosed (false).


 
 Example:  "true"
Responses 
200
OK


post/v3/storages/{storageId}/businesspartners/updateDisclosure
Request samples 
application/json
{
  • "disclosed": "true",
  • "dataSourceId": "648824a691d8d2503d65103e",
  • "countryCode": "DE",
  • "businessPartnerIds": [
    ]
}
Upsert Business PartnersWSDL
Upsert Business Partners in a Business Partner storage in batches. Maximum of 1000 Business Partners are allowed per batch.


If no data source (via field: dataSource) is provided and the storage has only one, then this data source will be used/set. Other options are to provide an
existing data source in the request, which will then be taken for all the Business Partner or to provide a data source for each Business Partner
individually.


In the following cases an API error will be thrown:


    

  1. given data source in the Request or the BusinessPartner is unknown
    2. 

  2. no data source given and more than one data source is attached to the storage
    3. 



To start upserting Business Partners into a storage, use the following request.


PUT https://api.corporate-data-league.ch/data-exchange/rest/v4/storages/{YOUR STORAGE ID}/businesspartners
{
  "dataSource": "{YOUR DATA SOURCE}",
  "featuresOn": ["UPSERT_BY_EXTERNAL_ID"],
  "businessPartners": [
   {
     "externalId": "123",
     "record": "{\"MyId\":\"123\", \"City\":\"St. Gallen\"}"
   }]
}



The response is shown below.


{
   "numberOfAccepted": "1",
   "numberOfFailed": "0",
}



Upserting Business Partners enables automated data transformation from the record field to the Business Partner model.
It requires a Data Mapper Definition and assigned to dataMapperDefinitionId field
of a data source Business Partner is being upserted to.


record field requires stringified JSON. Characters: backslash \ and double quote " must be escaped (respectively: \\\\ and \"). Fields containing . are unallowed."


To enable automated data transformation, one of the following features is required:


    

  • TRANSFORM_RECORD - synchronous transformation, limited for batch size <= 250,
    • 

  • ENABLE_ASYNC - asynchronous transformation. Enabled by default when TRANSFORM_RECORD is not requested.
    • 



Automated data transformation can be executed together with the UPSERT_BY_EXTERNAL_ID feature,
but it requires to provide external ID as a field externalId of a Business Partner,
which is preserved during the transformation.


If there is no name typed LOCAL in businessPartner.names
and exists any name with empty type or not filled type.technicalKey, it becomes name of type LOCAL.


Warn: in order to support multiple data sources, include dataSource into the request, either
in $.dataSource or $.businessPartners[*].dataSource. Otherwise, multiple data sources with no selection
of data source will lead to "No DataSource was provided for the given Business Partners and the storage
has more than one attached to it." exception.


Limits


Business Partner and Address fields have defined array size limits






Path
Max array size





$.businessPartners[*].names
20




$.businessPartners[*].identifiers
20




$.businessPartners[*].categories
20




$.businessPartners[*].addresses
20




$.businessPartners[*].relations
20




$.businessPartners[*].types
20




$.businessPartners[*].bankAccounts
50




$.businessPartners[*].profile.websites
20




$.businessPartners[*].profile.classifications
20




$.businessPartners[*].profile.contactEmails
20




$.businessPartners[*].profile.phoneNumbers
20




$.businessPartners[].addresses[].contexts
100




$.businessPartners[].addresses[].administrativeAreas
20




$.businessPartners[].addresses[].postCodes
20




$.businessPartners[].addresses[].localities
20




$.businessPartners[].addresses[].thoroughfares
20




$.businessPartners[].addresses[].premises
20




$.businessPartners[].addresses[].postalDeliveryPoints
20




$.businessPartners[].addresses[].types
20





SecurityapiKey 
Request 
path Parameters
storageId
required
string (BusinessPartnerStorageId) 
Unique identifier of the Storage.


 
 Example:  72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
Parameters for Business Partners Upsert.


required
Array of objects (BusinessPartner)   [ 1 .. 1000 ] items 
List of Business Partners.


 
dataSource
string (BusinessPartnerDataSource) 
Name or ID of a data source. Reflects the associated external system where the record originates from.


 
 Example:  "\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\""
featuresOff
Array of strings (UpsertFeatureParam) 
Features to be deactivated during the upsert.


Items Enum: Description
UPSERT_BY_EXTERNAL_ID
Updates a Business Partners identified by external ID instead of an insert if the external ID is already present in this storage.


API_ERROR_ON_FAILURES
Throws exception instead of default Upsert Failure Log.


TRANSFORM_RECORD
Transforms record into Business Partner model using the dataMapperDefinition attached to the dataSource. Supported only for batch size up to 250 Business Partners.


ENABLE_SETTINGS
Enables usage of user and organization settings in upsert process. Enabled by default.


ENABLE_ASYNC
Stores data to the storage. Enables asynchronous data processing for transformation, updates, indexing and sharing processes. Requires externalId to be present in the businessPartner. Enabled by default when TRANSFORM_RECORD not used.


 
 Example:  ["UPSERT_BY_EXTERNAL_ID"]
featuresOn
Array of strings (UpsertFeatureParam) 
Features to be activated during the upsert.


Items Enum: Description
UPSERT_BY_EXTERNAL_ID
Updates a Business Partners identified by external ID instead of an insert if the external ID is already present in this storage.


API_ERROR_ON_FAILURES
Throws exception instead of default Upsert Failure Log.


TRANSFORM_RECORD
Transforms record into Business Partner model using the dataMapperDefinition attached to the dataSource. Supported only for batch size up to 250 Business Partners.


ENABLE_SETTINGS
Enables usage of user and organization settings in upsert process. Enabled by default.


ENABLE_ASYNC
Stores data to the storage. Enables asynchronous data processing for transformation, updates, indexing and sharing processes. Requires externalId to be present in the businessPartner. Enabled by default when TRANSFORM_RECORD not used.


 
 Example:  ["UPSERT_BY_EXTERNAL_ID"]
Responses 
200
OK


put/v4/storages/{storageId}/businesspartners
Request samples 
application/json
{
  • "dataSource": "YOUR_DATASOURCE_ID",
  • "featuresOn": [
    ],
  • "businessPartners": [
    ]
}
Response samples 
application/json
{
  • "numberOfAccepted": "10",
  • "numberOfFailed": "10",
  • "failures": [
    ],
  • "featuresOn": [
    ]
}