# Business Partners Provides functionalities for creating, retrieving, updating, and deleting Business Partner records, as well as performing various operations such as lookup and upsert. ## List Business Partners - [GET /v4/storages/{storageId}/businesspartners](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v4~1storages~1%7Bstorageid%7D~1businesspartners/get.md): Read a page of business partners from the storage. ## Upsert Business Partners - [PUT /v4/storages/{storageId}/businesspartners](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v4~1storages~1%7Bstorageid%7D~1businesspartners/put.md): 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: ) 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) no data source given and more than one data source is attached to the storage To start upserting Business Partners into a storage, use the following request. The response is shown below. Upserting Business Partners enables automated data transformation from the field to the Business Partner model. It requires a Data Mapper Definition and assigned to field of a data source Business Partner is being upserted to. 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 of a Business Partner, which is preserved during the transformation. If there is no name typed LOCAL in and exists any name with empty type or not filled , 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[].contexts | 100 | | $.businessPartners[].administrativeAreas | 20 | | $.businessPartners[].postCodes | 20 | | $.businessPartners[].localities | 20 | | $.businessPartners[].thoroughfares | 20 | | $.businessPartners[].premises | 20 | | $.businessPartners[].postalDeliveryPoints | 20 | | $.businessPartners[].types | 20 | ## List Business Partners Updates - [GET /v5/storages/{storageId}/businesspartners/updates](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v5~1storages~1%7Bstorageid%7D~1businesspartners~1updates/get.md): 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 option. 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., , , ) with actions (e.g., , ). 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 works in pairs and identifies Business Partners where, for example, the was and this change was classified as . When filtering by tag and , 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 =. 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. We recommend periodically reading all Business Partners (at least once) to improve the efficiency of specific filtrations. ## Delete Business Partners - [POST /storages/{storageId}/businesspartners/delete](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1storages~1%7Bstorageid%7D~1businesspartners~1delete/post.md): 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. ## Toggle Business Partners Update Monitoring - [PUT /storages/{storageId}/businesspartners/toggleUpdateMonitoring](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1storages~1%7Bstorageid%7D~1businesspartners~1toggleupdatemonitoring/put.md): 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: * an attempt is taken to find Business Partner in all configured update monitors for non-commercial reference data sources and links are created if matches are found via defined linkage strategies * if the storage has UPDATES feature activated, updates for linked Business Partners from non-commercial reference data sources are propagated to Business Partner updates * 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. ## Start a Toggle Update Monitoring Job - [POST /jobs/toggleUpdateMonitoringJobs](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1jobs~1toggleupdatemonitoringjobs/post.md): 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. Or for a certain Country of a Data Source. This requires both parameters 'dataSourceId' and 'countryShortName' to be set 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: * an attempt is taken to find Business Partner in all configured update monitors for non-commercial reference data sources and links are created if matches are found via defined linkage strategies * if the storage has UPDATES feature activated, updates for linked Business Partners from non-commercial reference data sources are propagated to Business Partner updates * 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. ## Poll Toggle Update Monitoring Job - [GET /jobs/toggleUpdateMonitoringJobs/{jobId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1jobs~1toggleupdatemonitoringjobs~1%7Bjobid%7D/get.md): Poll endpoint for a job created in POST . ## Update Disclosure - [POST /v3/storages/{storageId}/businesspartners/updateDisclosure](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v3~1storages~1%7Bstorageid%7D~1businesspartners~1updatedisclosure/post.md): 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. 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. 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. Any other combination may result in a Bad Request. For more details, you can read about Sharing Scopes. ## Read Business Partner - [GET /v4/storages/{storageId}/businesspartners/{id}](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v4~1storages~1%7Bstorageid%7D~1businesspartners~1%7Bid%7D/get.md): Read Business Partner by ID. ## Lookup Business Partner - [POST /v4/storages/{storageId}/businesspartners/lookup](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v4~1storages~1%7Bstorageid%7D~1businesspartners~1lookup/post.md): Lookup a Business Partner in provided storage. ## Fetch Business Partner - [POST /v4/storages/{storageId}/businesspartners/fetch](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v4~1storages~1%7Bstorageid%7D~1businesspartners~1fetch/post.md): Fetch a Business Partner from this storage. ## Create Business Partner Tags - [POST /v4/storages/{storageId}/businesspartners/{businessPartnerId}/profile/tags](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v4~1storages~1%7Bstorageid%7D~1businesspartners~1%7Bbusinesspartnerid%7D~1profile~1tags/post.md): Allows the creation of Business Partner tags. The tags are created in the Business Partner profile. ## Delete Business Partner Tags - [POST /v4/storages/{storageId}/businesspartners/{businessPartnerId}/profile/tags/delete](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v4~1storages~1%7Bstorageid%7D~1businesspartners~1%7Bbusinesspartnerid%7D~1profile~1tags~1delete/post.md): Allows the deletion of Business Partner tags. The tags are deleted from the Business Partner profile. ## Random Business Partners (deprecated) - [GET /v4/storages/{storageId}/businesspartners/random](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partners/paths/~1v4~1storages~1%7Bstorageid%7D~1businesspartners~1random/get.md): Get random Business Partners from this storage.