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

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=2025-06-27T13:34:43Z
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": [
    ]
}