# Data Exchange API This API provides services to upload, manipulate and download businesspartner data in the CDL Cloud. Version: 5 ## Servers Production ``` https://api.cdq.com/data-exchange/rest ``` ## Security ### apiKey Type: apiKey In: header Name: X-API-KEY ## Download OpenAPI description [Data Exchange API](https://developer.cdq.com/_bundle/apis/data-exchange-api/@data-exchange-api-v5/api-v5.yaml) ## Seed Updates Manages operations such as creating, updating, or transforming Business Partner data to ensure that the information is current and accurate. ### Start Seed Updates Generate Job - [POST /v5/storages/{storageId}/seedupdates/generate](https://developer.cdq.com/apis/data-exchange-api/api-v5/seed-updates/paths/~1v5~1storages~1%7Bstorageid%7D~1seedupdates~1generate/post.md): Start a Seed Updates Generate Job for the given storage. ### Poll Seed Updates Generate Job - [GET /v5/storages/{storageId}/seedupdates/generate/{jobId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/seed-updates/paths/~1v5~1storages~1%7Bstorageid%7D~1seedupdates~1generate~1%7Bjobid%7D/get.md): Poll a Seed Updates Generate Job for the given storage. ## Business Partner Storages Provides functionalities for creating, retrieving, updating and deleting Business Partner storage, as well as managing associated data sources and data monitors. ### Update Storage - [PUT /storages/{storageId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D/put.md): Update a Business Partner Storage. ### Delete Storage - [DELETE /storages/{storageId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D/delete.md): Delete a Business Partner Storage. ### Roll Event Store - [POST /v2/storages/{storageId}/eventstore/roll](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1v2~1storages~1%7Bstorageid%7D~1eventstore~1roll/post.md): Roll Event Store for Business Partner Storage This endpoint facilitates the transition to a new event store for Business Partner Storage. The process involves several key steps: Validation: Ensure that the collection associated with previousEventStoreId does not exist. If it does, rolling to a new event store is prohibited. Creation: Establish a new collection intended to store events for the Business Partner Storage's event store. Backup: Safeguard the current eventStoreId by storing it as previousEventStoreId within the Business Partner Storage Metadata. Assignment: Update the Business Partner Storage Metadata by setting the new collection ID as the eventStoreId. Preservation: Retain the previousEventStoreId without dropping it, as it is now prepared for backup. This endpoint ensures a smooth transition while maintaining the integrity and accessibility of historical event data. ### Read Data Mirror - [GET /v5/storages/datamirror](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1v5~1storages~1datamirror/get.md): Read Data Mirror of the current workspace. ### Clear Storage - [POST /storages/{storageId}/clear](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D~1clear/post.md): Remove all Business Partners from given Business Partner Storage. ### Create Data Source - [POST /storages/{storageId}/datasources](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D~1datasources/post.md): Create a new data source. Max 100 data sources are allowed. Warn: If you have an integration with one data source, please check if data source id is included in the upsert request before adding a new data source. Otherwise, adding new data source may lead to upsert failures visible as bad request containing message "No DataSource was provided for the given Business Partners and the storage has more than one attached to it.". In case data source is created within DATA_MIRROR and does not have dataMapperDefinitionId or dataTransformationDefinitionId filled, dataMapperDefinitionId is set to default. ### Update Data Source - [PUT /storages/{storageId}/datasources/{dataSourceId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D~1datasources~1%7Bdatasourceid%7D/put.md): Update a Data Source. ### Delete Data Source - [DELETE /storages/{storageId}/datasources/{dataSourceId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D~1datasources~1%7Bdatasourceid%7D/delete.md): Delete a data source and its dependencies: * Business Partners from a storage, * update monitors, data monitors and sharing scopes for that data source are adjusted (data source is removed from the data sources list of a resource and resource is removed if data source was the only one assigned). ### Clear Data Source - [POST /storages/{storageId}/datasources/{dataSourceId}/clear](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D~1datasources~1%7Bdatasourceid%7D~1clear/post.md): Clear all Business Partners of a data source. ### Copy Data Source - [POST /storages/{storageId}/datasources/{dataSourceId}/copy](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D~1datasources~1%7Bdatasourceid%7D~1copy/post.md): Copy a data source between storages. ### Poll Copy Data Source Job Status - [GET /storages/{storageId}/datasources/{dataSourceId}/copy/{jobId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D~1datasources~1%7Bdatasourceid%7D~1copy~1%7Bjobid%7D/get.md): Allows polling the status of copy data source job ### List Update Monitors' Data Sources - [GET /v2/updatemonitors/referencedatasources](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1v2~1updatemonitors~1referencedatasources/get.md): List all data sources available for update monitoring. ### List Sharing Scopes - [GET /v4/storages/{storageId}/sharingscopes](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1v4~1storages~1%7Bstorageid%7D~1sharingscopes/get.md): List all sharing scopes of the give storage. ### Create Sharing Scope - [POST /v4/storages/{storageId}/sharingscopes](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1v4~1storages~1%7Bstorageid%7D~1sharingscopes/post.md): Create a new sharing scope. Max 100 sharing scopes are allowed. When creating sharing scope, all Business Partners from selection scope which are covered become disclosed. The following table presents the source for disclosed field. | Mapping disclosure | Sharing Scope matches | Source for disclosed | |---|---|---| | true | yes | Mapping disclosure | | true | no | Mapping disclosure | | false | yes | Sharing Scope | | false | no | default: false, otherwise from API request up to V4 | When source for disclosed field is Sharing Scope, the value is determined only during the creation of a Sharing Scope or Business Partner. Any new update of Business Partner doesn't overwrite the value of disclosed in the Business Partner. To change the disclosure of a concrete Business Partner, it has to be requested directly. > #### Note > > Business Partners with the Business Partner profile tag MARKED_FOR_DELETION are excluded from sharing and are not considered during Sharing Scope processing. ### Delete Sharing Scopes - [POST /v4/storages/{storageId}/sharingscopes/delete](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1v4~1storages~1%7Bstorageid%7D~1sharingscopes~1delete/post.md): Delete sharing scopes. When deleting sharing scope, all Business Partners from selection scope who are not included in any other sharing scopes, become undisclosed. ### Update Data Sources (deprecated) - [PUT /storages/{storageId}/datasources](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1storages~1%7Bstorageid%7D~1datasources/put.md): This endpoint is deprecated. Please use * create data source to create a new data source, * update data source to update existing data source, * delete data source to delete existing data source. Update all data sources of a given storage. * When a new data source without id is added to the list, it is created. In case data source is created within DATA_MIRROR and does not have dataMapperDefinitionId or dataTransformationDefinitionId filled, dataMapperDefinitionId is set to default. * When existing data source is provided on a list with id included, it is updated. * When data source identified by id is not included in a list, it is deleted with all its related Business Partners, data monitors and sharing scopes for that data source are adjusted (data source is removed from the data sources list of a resource and resource is removed if data source was the only one assigned). Note: all data sources that are expected to remain in the storage must be included on a list. Warn: If you have an integration with one data source, please check if data source id is included in the upsert request before adding a new data source. Otherwise, adding new data source may lead to upsert failures visible as bad request containing message "No DataSource was provided for the given Business Partners and the storage has more than one attached to it.". ### List Update Monitors' Data Sources (deprecated) - [GET /updatemonitors/datasources](https://developer.cdq.com/apis/data-exchange-api/api-v5/business-partner-storages/paths/~1updatemonitors~1datasources/get.md): List all data sources available for update monitoring. ## 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: 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) 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. 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 | ### 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 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. ### 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 toggleUpdateMonitoringJobs. ### 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. ### 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. ## Data Import Provides functionalities for uploading external data and enabling users to enhance and update their Business Partner records with new information. ### Start Import Job - [POST /jobs/importjobs](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-import/paths/~1jobs~1importjobs/post.md): To start importing a file into a storage, use the following request. POST https://api.corporate-data-league.ch/data-exchange/rest/jobs/importjobs ?file=@{YOUR FILE} ?storageId={YOUR STORAGE ID} ?dataSource={YOUR DATASOURCE ID} Fields (cells) in a file, that contain a special character (comma, semicolon, CR, LF, or double quote), must be "escaped" by enclosing them in double quotes. Header names can not contain any dot. In order to successfully perform file upload use file upload for files up to 10MB or Upload via Upload Request approach for files larger than 10MB. file and url are not allowed to be present together. Use one of the below instructions for your case: 1) File size 10MB : Request Upload Including this sample CSV file in the default configuration. Customer Number;City 123;St. Gallen Supported columns (matched by ignoring letter case) with their mappings are the following: | Column Name | Target Path in the latest Business Partner Model | Wiki Page of Attribute in CDQ Data Model | | ------- | -------- | -------- | | CUSTOMER NUMBER | $.externalId | Business Partner External ID | | VENDOR NUMBER | $.externalId when CUSTOMER NUMBER is not available | Business Partner External ID | | NAME | $.names\[0\].value, $.names\[0\].type.technicalKey = Business Partner External ID | Business Partner Name Value | | TAX NUMBER 1 | $.identifiers\[identifierId\].value in identifierId of TAX NUMBER 1 TYPE if exists, otherwise, new identifier of STCD1 type mapping, applied for COUNTRY | Business Partner Identifier Value | | TAX NUMBER 1 TYPE | $.identifiers\[identifierId\].type | Identifier type | | TAX NUMBER 2 | $.identifiers\[identifierId\].value in identifierId of TAX NUMBER 2 TYPE if exists, otherwise, new identifier of STCD2 type mapping, applied for COUNTRY | Business Partner Identifier Value | | TAX NUMBER 2 TYPE | $.identifiers\[identifierId\].type | Identifier type | | TAX NUMBER 3 | $.identifiers\[identifierId\].value in identifierId of TAX NUMBER 3 TYPE if exists, otherwise, new identifier of STCD3 type mapping, applied for COUNTRY | Business Partner Identifier Value | | TAX NUMBER 3 TYPE | $.identifiers\[identifierId\].type | Identifier type | | TAX NUMBER 4 | $.identifiers\[identifierId\].value in identifierId of TAX NUMBER 4 TYPE if exists, otherwise, new identifier of STCD4 type mapping, applied for COUNTRY | Business Partner Identifier Value | | TAX NUMBER 4 TYPE | $.identifiers\[identifierId\].type | Identifier type | | TAX NUMBER 5 | $.identifiers\[identifierId\].value in identifierId of TAX NUMBER 5 TYPE if exists, otherwise, new identifier of STCD5 type mapping, applied for COUNTRY | Business Partner Identifier Value | | TAX NUMBER 5 TYPE | $.identifiers\[identifierId\].type | Identifier type | | VAT NUMBER | $.identifiers\[identifierId\].value in identifierId of VAT NUMBER TYPE if exists, otherwise, new identifier of STCEG type mapping, applied for COUNTRY | Business Partner Identifier Value | | VAT NUMBER TYPE | $.identifiers\[identifierId\].type | Identifier type | | COUNTRY | address.country.(value, shortName) in $.addresses\[0\] (+ in $.addresses\[1\] when PO BOX exists for non-France) | Country | | REGION | address.administrativeAreas\[0\].value in $.addresses\[0\] (+ in $.addresses\[1\] when PO BOX exists for non-France) | Administrative Area Value| | POSTAL CODE | address.postCodes\[0\].value in $.addresses\[0\] (+ in $.addresses\[1\] when PO BOX exists for non-France) | Business Partner Post Code Value | | CITY | address.localities\[0\].value in $.addresses\[0\] (+ in $.addresses\[1\] when PO BOX exists for non-France) | Locality Value | | STREET | address.thoroughfares\[0\].value | Thoroughfare Value | | HOUSE NUMBER | address.thoroughfares\[0\].number | Thoroughfare Number | | PO BOX | address.postalDeliveryPoints\[0\].value, address.postalDeliveryPoints\[0\].type.technicalKey = PO BOX in $.addresses\[0\] in France, in $.addresses\[1\] for non-France | Business Partner External ID | Alternatively, CUSTOM_DATA_MAPPER feature can be used to enable record transformation based on the Data Mapper Definition provided either via a dataMapperDefinitionId field or assigned to provided data source. Input file could contain customized columns naming effectively mapped to the Business Partner model via data mapper, shown in this sample CSV. MyId;Country;City;Name 123;CH;St. Gallen; 124;CH;;Quote "Example" "125";"CH";"";"""Quote """"Example"""" """ Input file for CUSTOM_DATA_MAPPER feature can also contain only one Record column with a stringified JSON representation of a record. Based on the Data Mapper Definition, data is transformed to the Business Partner model. In case UPSERT_BY_EXTERNAL_ID feature is used, external ID value needs to be included: * in a column which name is provided via a extenalIdColumn request property * in the JSON representation in the attribute mapped to externalId via data mapper Below is the sample CSV file for Record-based configuration containing external ID column named MyId. MyId,Record 123,"{""MyId"": ""123"", ""Country"": ""CH"", ""City"": ""St. Gallen""}" 124,"{""MyId"": ""124"", ""Country"": ""CH"", ""Name"": ""Quote \""Example\""""}" 125,"{""MyId"": ""125"", ""Country"": ""CH"", ""Name"": ""\""Quote \""\""Example\""\"" \""""}" The maximum number of columns is 512 The response is shown below. Use the returned id to poll the import job status. { "id" : "{YOUR IMPORT JOB ID}" ... } These imports, in default import samples, lead to the following Business Partners in the storage. The imported rows are represented as stringifies JSONs. { "id" : "{AUTO GENERATED}", "externalId" : "123", "dataSource": "{YOUR DATASOURCE ID}", "record" : "{ \"MyId\" : \"123\", \"Country\" : \"CH\", \"City\" : \"St. Gallen\" }", "addresses": [{ "country": { "shortName": "CH" }, "localities": [{ "value": "St. Gallen" }] }], ... }, { "id" : "{AUTO GENERATED}", "externalId" : "124", "dataSource": "{YOUR DATASOURCE ID}", "record" : "{ \"MyId\" : \"124\", \"Country\" : \"CH\", \"Name\" : \"Quote \\\"Example\\\"\" }", "names": [{ "value": "Quote \"Example\"" ... }], "addresses": [{ "country": { "shortName": "CH" } }], ... }, { "id" : "{AUTO GENERATED}", "externalId" : "125", "dataSource": "{YOUR DATASOURCE ID}", "record" : "{ \"MyId\" : \"125\", \"Country\" : \"CH\", \"Name\" : \"\\\"Quote \\\"\\\"Example\\\"\\\" \\\"\" }", "names": [{ "value": "\"Quote \"\"Example\"\" \"" ... }], "addresses": [{ "country": { "shortName": "CH" } }], ... } Input file which first 100 data lines except header are corrupted is canceled without further processing. Importing data to Data Mirror requires using "UPSERT_BY_EXTERNAL_ID" feature. Otherwise, Bad Request is reported. ### Poll Import Job - [GET /jobs/importjobs/{jobId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-import/paths/~1jobs~1importjobs~1%7Bjobid%7D/get.md): Allows polling the status of an Import Job. ## 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. ### Create Data Mapper Definition - [POST /datamapperdefinitions](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mapping/paths/~1datamapperdefinitions/post.md): Create a Data Mapper Definition which is used to map data (i.e. in the format from the database) to the CDQ data model. Data mapper definition consists of: * inputMapping - definition how to map businessPartner.record to CDQ data model * outputMapping - definition how to map CDQ data model to the target model Business partner can be mapped via businessPartnerAttributeMappings. The following values of attribute mapping rules: - as targetAttributes for inputMapping - as sourceAttributes for outputMapping (please remember they are case sensitive) can be mapped to Business Partner attributes: - businessPartner.dataSource - businessPartner.externalId - businessPartner.disclosed - special attribute. When defined in a mapping, takes over the decision for disclosing records in data source this Data Mapper Definition is assigned to. When source attribute is mapped from record, the mapping takes the value. If the attribute is missing, disclosed is set to false. - businessPartner.names\[0-10\].value - businessPartner.names\[0-10\].shortName - businessPartner.names\[0-10\].language - businessPartner.names\[0-10\].type - businessPartner.names - businessPartner.legalForm.name - businessPartner.legalForm.categories\[0-4\].technicalKey - businessPartner.categories - businessPartner.identifiers\[0-49\].value - businessPartner.identifiers\[0-49\].type - businessPartner.identifiers\[0-49\].issuingBody.name - businessPartner.identifiers\[0-49\].issuingBody - mapped to issuingBody.technicalKey - businessPartner.identifiers\[0-49\].status - businessPartner.identifiers - businessPartner.externalContext.identifiers\[0-49\].value - businessPartner.externalContext.identifiers\[0-49\].type - businessPartner.externalContext.identifiers The index of typed concepts: names and identifiers, is not a final position of concept in the CDQ data model - this is a grouping indicator for a set of concept properties. In Names mapping, in case none of names is typed LOCAL. and exists any name with empty type or not filled type.technicalKey, it becomes name of type LOCAL. Addresses can be mapped via addressesAttributeMappings. Address receives id property coming from an index of the collection of AttributeMappingRules. The following values of attribute mapping rules - as targetAttributes for inputMapping - as sourceAttributes for outputMapping can be mapped to address attributes: - address.externalId - address.version.language - address.version.characterSet - address.careOf.value - address.identifyingName.value - address.country.value - address.country.shortName - address.administrativeAreas - address.administrativeAreas\[0-4\].value - address.administrativeAreas\[0-4\].shortName - address.administrativeAreas\[0-4\].type - address.postCodes - address.postCodes\[0-4\].value - address.postCodes\[0-4\].type - address.localities - address.localities\[0-4\].value - address.localities\[0-4\].shortName - address.localities\[0-4\].type - address.thoroughfares - address.thoroughfares\[0-4\].value - address.thoroughfares\[0-4\].shortName - address.thoroughfares\[0-4\].number - address.thoroughfares\[0-4\].type - address.premises - address.premises\[0-4\].value - address.premises\[0-4\].shortName - address.premises\[0-4\].number - address.premises\[0-4\].type - address.postalDeliveryPoints - address.postalDeliveryPoints\[0-4\].value - address.postalDeliveryPoints\[0-4\].shortName - address.postalDeliveryPoints\[0-4\].number - address.postalDeliveryPoints\[0-4\].type - address.geographicCoordinates.latitude - address.geographicCoordinates.longitude - address.contexts - address.contexts\[0-4\] ### List Data Mapper Definitions - [GET /datamapperdefinitions](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mapping/paths/~1datamapperdefinitions/get.md): Read the Data Mapper Definition Page. ### Read Data Mapper Definition - [GET /datamapperdefinitions/{id}](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mapping/paths/~1datamapperdefinitions~1%7Bid%7D/get.md): Read a Data Mapper Definition. ### Update Data Mapper Definition - [PUT /datamapperdefinitions/{id}](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mapping/paths/~1datamapperdefinitions~1%7Bid%7D/put.md): Update a Data Mapper Definition. For more information what are the allowed Data Mapper values, go to creation endpoint description. ### Delete Data Mapper Definition - [DELETE /datamapperdefinitions/{id}](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mapping/paths/~1datamapperdefinitions~1%7Bid%7D/delete.md): Delete chosen Data Mapper Definition. ## Data Monitors Provides functionalities for creating, retrieving, updating and deleting data monitors. ### List Data Monitors by Type - [GET /v2/datamonitors](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-monitors/paths/~1v2~1datamonitors/get.md): List all Data Monitors of a specific type across all storages. ### Delete Data Monitor - [DELETE /storages/{storageId}/datamonitors/{dataMonitorId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-monitors/paths/~1storages~1%7Bstorageid%7D~1datamonitors~1%7Bdatamonitorid%7D/delete.md): Delete a data monitor. ### List Data Monitors - [GET /v2/storages/{storageId}/datamonitors](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-monitors/paths/~1v2~1storages~1%7Bstorageid%7D~1datamonitors/get.md): List all Data Monitors of the give storage. ### Create Data Monitor - [POST /v2/storages/{storageId}/datamonitors](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-monitors/paths/~1v2~1storages~1%7Bstorageid%7D~1datamonitors/post.md): Create a new data monitor. Data monitor is a concept for asynchronous processing of data curation and data validation. Data monitors should be unique by a pair: dataSources + type. Data monitor can be created only for DATA_MIRROR storage, having sharedWithOrganization set to true. Available execution types: * TRIGGER - causes reevaluation of data whenever CDQ Business Partner model of your data has changed or whenever linked reference data has changed * JOB - reevaluates data every specified period of time. Note: creation of data monitor starts background process that is invoked for all Business Partners from data monitor scope. ### Update Data Monitor - [PUT /v2/storages/{storageId}/datamonitors/{dataMonitorId}](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-monitors/paths/~1v2~1storages~1%7Bstorageid%7D~1datamonitors~1%7Bdatamonitorid%7D/put.md): Note: modification of configuration.id or set of dataSources starts background process that populates processing log for all Business Partners from data monitor scope. ### Data Monitor Progress - [GET /v2/storages/{storageId}/datamonitors/{dataMonitorId}/progress](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-monitors/paths/~1v2~1storages~1%7Bstorageid%7D~1datamonitors~1%7Bdatamonitorid%7D~1progress/get.md): Note: modification of configuration.id or set of dataSources starts background process that populates processing log for all Business Partners from data monitor scope. ### Refresh Data Monitors - [POST /v2/storages/{storageId}/datamonitors/refresh](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-monitors/paths/~1v2~1storages~1%7Bstorageid%7D~1datamonitors~1refresh/post.md): Refresh Data Monitors. When refreshing data monitor, a reevaluation is done for all Business Partners from the data monitor scope. ## Data Transformation Provides functionalities for converting raw data into structured formats. ### Start Transformation Job - [POST /jobs/transformationjobs](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-transformation/paths/~1jobs~1transformationjobs/post.md): Starting a Transformation Job. In case any selected data source does not have a dataMappingDefinition an API error returned. ### Poll Transformation Job - [GET /jobs/transformationjobs/{id}](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-transformation/paths/~1jobs~1transformationjobs~1%7Bid%7D/get.md): After you have started a transformation job, you will receive a job id in the response. { "id" : "" } Use this ID to poll for the status of the job using this endpoint. Once the status is FINISHED the transformation is done, and you are able to verify the result in your storage. ### Use Data Mapper Definition (deprecated) - [POST /v3/datamappers/{id}/transform](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-transformation/paths/~1v3~1datamappers~1%7Bid%7D~1transform/post.md): Use a Data Mapper Definition to transform a list of records into Business Partners. ## DNB Storages Provides functionalities for creating, retrieving, updating and deleting DNB storage, as well as managing associated data sources and data monitors. ### List DNB Records - [GET /v5/dnbstorages/dnbrecords](https://developer.cdq.com/apis/data-exchange-api/api-v5/dnb-storages/paths/~1v5~1dnbstorages~1dnbrecords/get.md): Read a page of records from the D&B storage of your organization. ### Start DNB Import Job - [POST /jobs/dnbimportjobs](https://developer.cdq.com/apis/data-exchange-api/api-v5/dnb-storages/paths/~1jobs~1dnbimportjobs/post.md): To start a D&B Import Job use the following request curl -X POST \ --url 'https://api.corporate-data-league.ch/data-exchange/rest/jobs/dnbimportjobs?dnbUser=optional&dnbPassword=optional' \ -u 'BasicAuthUserName:your_credentials'\ -H 'Accept: application/json' \ -F 'file=@your_file.csv' with using this sample file: DUNS 305211311 DNB:305211311 The file can be a csv or xlsx. The file should contain only one column with the DUNS number. In the first row should the header DUNS. The DUNS number can be in following forms: - As CDQ-ID. Example or DNB:305211311 - as raw DUNS 305211311 The DUNS consist of 9 digits. When the input DUNS does not consist of 9 digits, leading zeros are added. ### Poll DNB Import Job - [GET /jobs/dnbimportjobs/{id}](https://developer.cdq.com/apis/data-exchange-api/api-v5/dnb-storages/paths/~1jobs~1dnbimportjobs~1%7Bid%7D/get.md): After you have started a D&B import job, you will receive a job id in the response. { "id" : "" } Use this ID to poll for the status of the job using this endpoint. Once the status is FINISHED, you can see the results in the D&B storage. ### Create LOD File - [POST /jobs/dnbcreatelodjobs](https://developer.cdq.com/apis/data-exchange-api/api-v5/dnb-storages/paths/~1jobs~1dnbcreatelodjobs/post.md): For all data mirrors configured for an organization, read Business Partners identifiers with type DUNS_ID and create a list of the DUNS file. This file is used to initialize the D&B Monitoring process. ### Poll DNB LOD Job - [GET /jobs/dnbcreatelodjobs/{id}](https://developer.cdq.com/apis/data-exchange-api/api-v5/dnb-storages/paths/~1jobs~1dnbcreatelodjobs~1%7Bid%7D/get.md): After you have started a D&B LOD job, you will receive a job id in the response. { "id" : "" } Use this ID to poll for the status of the job using this endpoint. Once the status is FINISHED, you can see the results in the attachments. ### Fetch DNB Record - [POST /v4/dnbstorages/fetch](https://developer.cdq.com/apis/data-exchange-api/api-v5/dnb-storages/paths/~1v4~1dnbstorages~1fetch/post.md): Fetch a D&B record by providing the DUNS. ## Files Provides functionalities for uploading, downloading and deleting files. ### Request File Upload - [POST /v5/files/upload](https://developer.cdq.com/apis/data-exchange-api/api-v5/files/paths/~1v5~1files~1upload/post.md): Create a file in the file storage using the url provided. Maximum allowed file size is 300 MiB. ### List Files - [GET /v5/files](https://developer.cdq.com/apis/data-exchange-api/api-v5/files/paths/~1v5~1files/get.md): Returns a list of all files that are available at the specific url path. ### Request File Download - [POST /v5/files/download](https://developer.cdq.com/apis/data-exchange-api/api-v5/files/paths/~1v5~1files~1download/post.md): Request a download link for a file stored in CDQ Cloud. Files undergo mandatory malware scanning before they become available for download. The response returns HTTP 200 or 400, depending on scan status and result. When status.details.technicalKey contains FILE_SCANNING, the file is still being scanned, and download.link is absent. The client should poll this endpoint until FILE_SCANNING changes to FILE_AVAILABLE. When status.details.technicalKey contains FILE_AVAILABLE, download.link contains a presigned URL valid for the requested duration. When status.details.technicalKey is FILE_REJECTED, the file failed the malware scan, and download.link will never be provided. ### Request Files Delete - [DELETE /files](https://developer.cdq.com/apis/data-exchange-api/api-v5/files/paths/~1files/delete.md): Delete files in the customer-uploads directory using the provided urls. ### List All Resources - [GET /files/resources](https://developer.cdq.com/apis/data-exchange-api/api-v5/files/paths/~1files~1resources/get.md): Returns list of all resources, which are available at the specific url path. ## 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. ### Transform Records - [POST /v4/datamapperdefinitions/{id}/transformBusinessPartners](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mappers/paths/~1v4~1datamapperdefinitions~1%7Bid%7D~1transformbusinesspartners/post.md): Use a Data Mapper Definition to transform a list of records into Business Partners. ### Transform Business Partners - [POST /v4/datamapperdefinitions/{id}/transformFields](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mappers/paths/~1v4~1datamapperdefinitions~1%7Bid%7D~1transformfields/post.md): Use a Data Mapper Definition to transform a list of Business Partners into key-value lists. ### Transform Records (deprecated) - [POST /v3/datamappers/{id}/transformBusinessPartners](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mappers/paths/~1v3~1datamappers~1%7Bid%7D~1transformbusinesspartners/post.md): Use a Data Mapper Definition to transform a list of records into Business Partners. ### Transform Business Partners (deprecated) - [POST /v3/datamappers/{id}/transformFields](https://developer.cdq.com/apis/data-exchange-api/api-v5/data-mappers/paths/~1v3~1datamappers~1%7Bid%7D~1transformfields/post.md): Use a Data Mapper Definition to transform a list of Business Partners into key-value lists. ## Relations Manages relationships between Business Partners. ### Initialize Storage relations - [POST /v4/storages/{storageId}/relations](https://developer.cdq.com/apis/data-exchange-api/api-v5/relations/paths/~1v4~1storages~1%7Bstorageid%7D~1relations/post.md): Initialize relations in a Business Partner Storage. ### List Relations - [GET /v4/storages/{storageId}/relations](https://developer.cdq.com/apis/data-exchange-api/api-v5/relations/paths/~1v4~1storages~1%7Bstorageid%7D~1relations/get.md): Read a page of relations from a Business Partner Storage. ### Upsert Business Partner Relations - [PUT /v4/storages/{storageId}/relations](https://developer.cdq.com/apis/data-exchange-api/api-v5/relations/paths/~1v4~1storages~1%7Bstorageid%7D~1relations/put.md): Insert or update Business Partner Relations. Relations that are not listed in the request are not modified. In D&B storages, not-listed relations of class BUSINESS_PARTNER_RELATION_CLASS_DNB_HIERARCHY and type COMMERCIAL_ULTIMATE or DOMESTIC_COMMERCIAL_ULTIMATE are marked as INACTIVE. Check the wiki's Business Partner Relation Class and Business Partner Relation Type for more details about the mentioned types and classes. ### Delete relations - [POST /v4/storages/{storageId}/relations/delete](https://developer.cdq.com/apis/data-exchange-api/api-v5/relations/paths/~1v4~1storages~1%7Bstorageid%7D~1relations~1delete/post.md): Delete relations from a storage. ## Subscriptions Provides functionalities for managing subscriptions. ### List Links - [GET /v4/businesspartners/identitylinks](https://developer.cdq.com/apis/data-exchange-api/api-v5/subscriptions/paths/~1v4~1businesspartners~1identitylinks/get.md): Reads a page of links of the Business Partners starting from the 'startAfter' and with a size of 'limit'.