Business Partners

Delete Business Partners

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 delete, but the data source itself will not be deleted.

SecurityapiKey
Request
path Parameters
storageId
required
string

storageId

Request Body schema: application/json

cmd

Array of objects <= 1000 items
dataSource
string

ID of a data source.

featuresOn
Array of strings (DeleteFeature)
Items Value: "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": 0,
  • "numberOfFailures": 0,
  • "failures": [
    ]
}

Fetch Business Partner

Fetch a Business Partner from this storage

SecurityapiKey
Request
path Parameters
storageId
required
string

storageId

Request Body schema: application/json
dataSource
string
externalId
required
string (BusinessPartnerExternalId)

ID the record has in the external system where the record originates from.

featuresOff
Array of strings (FetchBusinessPartnerFeatureParam)

Feature(s) to be excluded during the fetch business partner:

  • 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 turned off. Only for storages with RELATIONS feature enabled
Items Enum: "FETCH_RECORD" "FETCH_RELATIONS"
featuresOn
Array of strings (FetchBusinessPartnerFeatureParam)

Feature(s) to be used during the fetch business partner:

  • 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 turned off. Only for storages with RELATIONS feature enabled
Items Enum: "FETCH_RECORD" "FETCH_RELATIONS"
Responses
200

OK

401

Unauthorized

403

Forbidden

post/v4/storages/{storageId}/businesspartners/fetch
Request samples
application/json
{
  • "externalId": "string",
  • "dataSource": "string",
  • "featuresOn": [
    ],
  • "featuresOff": [
    ]
}
Response samples
application/json
{
  • "businessPartner": {
    },
  • "status": "string",
  • "message": "string"
}

Lookup Business Partner

Lookup a Business Partner in this storage.

SecurityapiKey
Request
path Parameters
storageId
required
string

storageId

Request Body schema: application/json

cmd

required
object (BusinessPartnerLookupParam)
dataSources
Array of strings
featuresOff
Array of strings (FetchBusinessPartnerFeatureParam)

Feature(s) to be excluded during the fetch business partner:

  • 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 turned off. Only for storages with RELATIONS feature enabled
Items Enum: "FETCH_RECORD" "FETCH_RELATIONS"
featuresOn
Array of strings (FetchBusinessPartnerFeatureParam)

Feature(s) to be used during the fetch business partner:

  • 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 turned off. Only for storages with RELATIONS feature enabled
Items Enum: "FETCH_RECORD" "FETCH_RELATIONS"
matchingThreshold
number <double> [ 0 .. 1 ]
Default: 0
page
integer >= 0
Default: 0
pageSize
integer [ 1 .. 1000 ]
Default: 10
Responses
200

OK

401

Unauthorized

403

Forbidden

404

Not Found

post/v4/storages/{storageId}/businesspartners/lookup
Request samples
application/json
{
  • "matchingThreshold": 0,
  • "pageSize": 10,
  • "page": 0,
  • "dataSources": [
    ],
  • "businessPartner": {
    },
  • "featuresOn": [
    ],
  • "featuresOff": [
    ]
}
Response samples
application/json
{
  • "pageSize": 0,
  • "total": 0,
  • "page": 0,
  • "values": [
    ],
  • "debugInfo": {
    }
}

Poll Toggle Update Monitoring Job

SecurityapiKey
Request
path Parameters
jobId
required
string

jobId

Responses
200

OK

get/jobs/toggleUpdateMonitoringJobs/{jobId}
Request samples
curl -i -X GET \
  'https://api.cdq.com/data-exchange/rest/jobs/toggleUpdateMonitoringJobs/{jobId}' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "job": {
    },
  • "status": "string"
}

Random Business Partners

Get random Business Partners from this storage

SecurityapiKey
Request
path Parameters
storageId
required
string

storageId

query Parameters
countryCode
string

A country code used to filter the result of business partners returned.

dataSource
string

Data source (name or ID) used to filter the result of business partners returned.

featureOff
Array of strings (FetchBusinessPartnerFeatureParam)

Feature(s) to be excluded during the fetch business partner:

  • 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 turned off. Only for storages with RELATIONS feature enabled
Items Enum: "FETCH_RECORD" "FETCH_RELATIONS"
featureOn
Array of strings (FetchBusinessPartnerFeatureParam)

Feature(s) to be used during the fetch business partner:

  • 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 turned off. Only for storages with RELATIONS feature enabled
Items Enum: "FETCH_RECORD" "FETCH_RELATIONS"
limit
integer <int32> [ 1 .. 10 ]
Default: 1

Number of items to be returned on the page.

modifiedAfter
string

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

Example: modifiedAfter=2020-07-06T12:14:03.204Z
modifiedBefore
string

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

Example: modifiedBefore=2020-07-06T12:14:03.204Z
Responses
200

OK

401

Unauthorized

403

Forbidden

get/v4/storages/{storageId}/businesspartners/random
Request samples
curl -i -X GET \
  'https://api.cdq.com/data-exchange/rest/v4/storages/{storageId}/businesspartners/random?countryCode=string&dataSource=string&featureOff=FETCH_RECORD&featureOn=FETCH_RECORD&limit=1&modifiedAfter=string&modifiedBefore=string' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "limit": 0,
  • "values": [
    ]
}

Read Business Partner

SecurityapiKey
Request
path Parameters
id
required
string

id

storageId
required
string

storageId

query Parameters
featureOff
Array of strings (ReadBusinessPartnerFeatureParam)

Feature(s) to be used during the read business partner:

  • APPLY_CURATION_DECISIONS - Applies curation decisions from Decision Log to business partner if any decisions found. By default turned off.
  • 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 turned off. Only for storages with RELATIONS feature enabled
Items Enum: "APPLY_CURATION_DECISIONS" "FETCH_RECORD" "FETCH_RELATIONS"
featureOn
Array of strings (ReadBusinessPartnerFeatureParam)

Feature(s) to be used during the read business partner:

  • APPLY_CURATION_DECISIONS - Applies curation decisions from Decision Log to business partner if any decisions found. By default turned off.
  • 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 turned off. Only for storages with RELATIONS feature enabled
Items Enum: "APPLY_CURATION_DECISIONS" "FETCH_RECORD" "FETCH_RELATIONS"
Responses
200

OK

get/v4/storages/{storageId}/businesspartners/{id}
Request samples
curl -i -X GET \
  'https://api.cdq.com/data-exchange/rest/v4/storages/{storageId}/businesspartners/{id}?featureOff=APPLY_CURATION_DECISIONS&featureOn=APPLY_CURATION_DECISIONS' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "id": "string",
  • "createdAt": "string",
  • "lastModifiedAt": "string",
  • "externalId": "string",
  • "dataSource": "string",
  • "disclosed": true,
  • "updateMonitoring": true,
  • "metadata": {
    },
  • "record": "string",
  • "additionalInformation": [
    ],
  • "names": [
    ],
  • "legalForm": {},
  • "identifiers": [
    ],
  • "categories": [
    ],
  • "status": {
    },
  • "profile": {
    },
  • "relations": [
    ],
  • "types": [
    ],
  • "addresses": [
    ],
  • "bankAccounts": [
    ]
}

Read Business Partners

SecurityapiKey
Request
path Parameters
storageId
required
string

storageId

query Parameters
businessPartnerId
Array of strings

Business Partner IDs which should be filtered.

countryCode
Array of strings

Country short names used to filter the result of business partners returned.

curationLogResultStatus
Array of strings (CurationLevelParam)

Curation log of curation result.

Items Enum: "LEVEL_1" "LEVEL_2" "LEVEL_3" "LEVEL_4" "LEVEL_5" "LEVEL_6" "UNKNOWN"
dataSource
Array of strings

Data source (names or IDs) used to filter the result of business partners returned.

externalId
Array of strings

Business Partner externalIDs which should be filtered.

featuresOff
Array of strings (BusinessPartnersReadFeatureParam)

Features to be turned off:

  • APPLY_CURATION_DECISIONS - Applies curation decisions from Decision Log to business partners if any decisions found. By default turned off.
  • 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 turned off. Only for storages with RELATIONS feature enabled.
  • 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 automatically calculate pagination indicator in nextStartAfter field. By default turned off.
Items Enum: "APPLY_CURATION_DECISIONS" "FETCH_RECORD" "FETCH_RELATIONS" "NUMBER_OF_TOTAL" "USE_NEXT_START_AFTER"
featuresOn
Array of strings (BusinessPartnersReadFeatureParam)

Features to be turned on:

  • APPLY_CURATION_DECISIONS - Applies curation decisions from Decision Log to business partners if any decisions found. By default turned off.
  • 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 turned off. Only for storages with RELATIONS feature enabled.
  • 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 automatically calculate pagination indicator in nextStartAfter field. By default turned off.
Items Enum: "APPLY_CURATION_DECISIONS" "FETCH_RECORD" "FETCH_RELATIONS" "NUMBER_OF_TOTAL" "USE_NEXT_START_AFTER"
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=2022-04-04T12:44:03.240Z
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=2022-04-04T12:44:03.240Z
hasRawData
boolean
Default: false

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

limit
integer <int32> >= 1
Default: 500

Number of items to be returned on the page.

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" "JOB"
modifiedAfter
string

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

Example: modifiedAfter=2020-07-06T12:14:03.204Z
modifiedBefore
string

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

Example: modifiedBefore=2020-07-06T12:14:03.204Z
query
string
reviewStatus
string (ReviewStatusParam)

Review status used for filtering the result data.

Enum: "REVIEWED" "NOT_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
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.

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=2022-04-04T12:44:03.240Z
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=2022-04-04T12:44:03.240Z
updateMonitoring
boolean

Flag to filter business partners by the value of updateMonitoring attribute

validationLogResultStatus
Array of strings (ValidationLevelParam)

Violation level of validation result.

Items Enum: "ERROR" "WARNING" "INFO" "NO_DEFECTS"
validationSharingLogResultStatus
Array of strings (ValidationLevelParam)

Violation level of sharing validation result.

Items Enum: "ERROR" "WARNING" "INFO" "NO_DEFECTS"
Responses
200

OK

400

Bad Request

401

Unauthorized

get/v4/storages/{storageId}/businesspartners
Request samples
curl -i -X GET \
  'https://api.cdq.com/data-exchange/rest/v4/storages/{storageId}/businesspartners?businessPartnerId=string&countryCode=string&curationLogResultStatus=LEVEL_1&dataSource=string&externalId=string&featuresOff=APPLY_CURATION_DECISIONS&featuresOn=APPLY_CURATION_DECISIONS&fromJobProcessedAt=string&fromTriggerProcessedAt=string&hasRawData=false&limit=500&logResultTriggerType=CREATED&modifiedAfter=string&modifiedBefore=string&query=string&reviewStatus=REVIEWED&sharingStatus=string&startAfter=string&toJobProcessedAt=string&toTriggerProcessedAt=string&updateMonitoring=true&validationLogResultStatus=ERROR&validationSharingLogResultStatus=ERROR' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "startAfter": "string",
  • "limit": 0,
  • "total": 0,
  • "values": [
    ],
  • "nextStartAfter": "string"
}

Read Business Partners Updates

Example Response:

{
  "values": [
    {
      "businessPartner": {
        "id": "123456",
        "externalId": "EXTID-86",
        ...,
        "record": "{<JSON>}"
      },
      "provenances": [
        {
          "name": "Supplier Gateway",
          "technicalKey": "SGW"
        }
      ],
      "changeSet": [
        {
          "modifiedAt": "2007-08-31T16:47",
          "propertyChanges": [
            {
              "newContent": "AAB",
              "previousContent": "XYZ",
              "changeType": "MODIFIED",
              "changeClassification": "MAJOR",
              "provenance": {
                "name": "Supplier Gateway",
                "technicalKey": "SGW"
              },
              "property": {
                "name": "Minority Indicator Value",
                "contentSelector": "$.profile.minorityIndicator.value",
                "technicalKey": "MINORITY_INDICATOR_VALUE"
                "parentConcept": {
                  "name": "Minority Indicator",
                  "technicalKey": "MINORITY_INDICATOR"
                }
              }
            }
          ],
          "provenances": [
            {
              "name": "Supplier Gateway",
              "technicalKey": "SGW"
            }
          ]
        }
      ]
    }
  ]
}

In typed concepts, like Name, Identifier or Premise, type.technicalKey and any non-empty property are required to be filled in order to monitor updates.

SecurityapiKey
Request
path Parameters
storageId
required
string

storageId

query Parameters
affectedConcepts
Array of strings (BusinessPartnerConceptParam)

Only show updates which affected these concepts

Items Enum: "NAME" "IDENTIFIER" "LEGAL_FORM" "MINORITY_INDICATOR" "STATUS" "ADDRESS" "COUNTRY" "ADMINISTRATIVE_AREA" "POST_CODE" "LOCALITY" "THOROUGHFARE" "PREMISE" "POSTAL_DELIVERY_POINT" "GEO_COORDINATES" "GEOGRAPHIC_COORDINATES"
Example: affectedConcepts=MINORITY_INDICATOR
affectedProperties
Array of strings (BusinessPartnerPropertyParam)

Only show updates which affected these properties

Items Enum: "NAME_VALUE" "IDENTIFIER_VALUE" "MINORITY_INDICATOR_VALUE" "ADMINISTRATIVE_AREA_VALUE" "LOCALITY_VALUE" "POST_CODE_VALUE" "THOROUGHFARE_VALUE" "THOROUGHFARE_NUMBER" "BUSINESS_PARTNER_STATUS_TYPE" "LEGAL_FORM_NAME"
Example: affectedProperties=MINORITY_INDICATOR_VALUE
businessPartnerIds
Array of strings <= 500 items

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

changeClassification
string (PropertyChangeClassificationParam)

Filter for change classifications

Enum: "MINOR" "MAJOR"
changeType
string

Filter for change types

Enum: "ADDED" "MODIFIED" "DELETED"
countryShortName
Array of strings

Filter for countries

dataSource
Array of strings

Filter for a data source (name or id)

exceptProvenanceTechnicalKeys
Array of strings

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

featuresOff
Array of strings (BusinessPartnerUpdatesFeatureParam)

Features to be used during the read business partners updates:

  • SHOW_BUSINESS_PARTNER - Show businss partner merged out of updates in `$.values[*].businessPartner. By default turned off.
  • FETCH_STORAGE_BUSINESS_PARTNER - Fetch business partner from a storage and set in $.values[*].storageBusinessPartner. By default turned off.
  • NUMBER_OF_TOTAL - Allows to switch fetching the total number of records to improve performance. By default turned on.
Items Enum: "SHOW_BUSINESS_PARTNER" "FETCH_STORAGE_BUSINESS_PARTNER"
featuresOn
Array of strings (BusinessPartnerUpdatesFeatureParam)

Features to be used during the read business partners updates:

  • SHOW_BUSINESS_PARTNER - Show businss partner merged out of updates in `$.values[*].businessPartner. By default turned off.
  • FETCH_STORAGE_BUSINESS_PARTNER - Fetch business partner from a storage and set in $.values[*].storageBusinessPartner. By default turned off.
  • NUMBER_OF_TOTAL - Allows to switch fetching the total number of records to improve performance. By default turned on.
Items Enum: "SHOW_BUSINESS_PARTNER" "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=2019-12-31T16:47
limit
integer <int32> >= 1
Default: 500

Number of items to be returned on the page.

provenanceTechnicalKeys
Array of strings

Show updates for selected provenances by technical keys

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.

Responses
200

OK

get/v4/storages/{storageId}/businesspartners/updates
Request samples
curl -i -X GET \
  'https://api.cdq.com/data-exchange/rest/v4/storages/{storageId}/businesspartners/updates?affectedConcepts=MINORITY_INDICATOR&affectedProperties=MINORITY_INDICATOR_VALUE&businessPartnerIds=string&changeClassification=MINOR&changeType=ADDED&countryShortName=string&dataSource=string&exceptProvenanceTechnicalKeys=string&featuresOff=SHOW_BUSINESS_PARTNER&featuresOn=SHOW_BUSINESS_PARTNER&from=2019-12-31T16%3A47&limit=500&provenanceTechnicalKeys=string&startAfter=string' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "limit": 0,
  • "total": 0,
  • "startAfter": "string",
  • "nextStartAfter": "string",
  • "values": [
    ]
}

Start 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. 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:
  • if enable is false then:
    • all existing links of a business partner to business partners in reference data sources are removed
    • updates are no more propagated for this business partner
    • linkage is not performed for any 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
countryShortName
string (CountryShortName)

Country code (ISO 3166-1 alpha-2).

dataSourceId
required
string (BusinessPartnerStorageDataSourceId)

Unique identifier for a data source of a storage

enable
required
boolean (ToggleUpdateMonitoringRequestEnable)

Parameter to describe if the Business Partners should be enabled for update monitoring (true) or disabled (false).

storageId
required
string (BusinessPartnerStorageId)
Responses
200

OK

post/jobs/toggleUpdateMonitoringJobs
Request samples
application/json
{
  • "enable": true,
  • "storageId": "string",
  • "dataSourceId": "18d06d2d-bc67-4d2b-944e-a8fc52fa981a",
  • "countryShortName": "CH"
}
Response samples
application/json
{
  • "id": "string",
  • "createdBy": "string",
  • "createdAt": "string",
  • "modifiedAt": "string",
  • "progress": 0,
  • "status": "RUNNING",
  • "statusMessage": "string",
  • "enable": true,
  • "storageId": "string",
  • "dataSourceId": "18d06d2d-bc67-4d2b-944e-a8fc52fa981a",
  • "countryShortName": "CH"
}

Toggle Update Monitoring of Business Partners

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 reference data sources are removed
    • updates are no more propagated for this business partner
    • linkage is not performed for any 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

storageId

Request Body schema: application/json
businessPartnerIds
required
Array of strings [ 1 .. 1000 ] items

List of Business Partner IDs to identify all those Business Partners that should be enabled/disabled.

enable
required
boolean (ToggleUpdateMonitoringRequestEnable)

Parameter to describe if the Business Partners should be enabled for update monitoring (true) or disabled (false).

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

For more details, you can read about Sharing Scopes.

SecurityapiKey
Request
path Parameters
storageId
required
string

storageId

Request Body schema: application/json
businessPartnerIds
Array of strings non-empty

List of BusinessPartner IDs to identify all those BusinessPartners that should be un-/disclose.

countryCode
string
Deprecated

A country code (ISO 3166-2), to be used in combination with a DataSource ID to un-/disclose all matching BusinessPartners.

dataSourceId
string
Deprecated

A DataSource ID for which all related BusinessPartners should be un-/disclose

disclosed
required
boolean

Parameter to describe if the BusinessPartners should be disclosed (true) or undisclosed (false).

Responses
200

OK

post/v3/storages/{storageId}/businesspartners/updateDisclosure
Request samples
application/json
{
  • "disclosed": true,
  • "dataSourceId": "string",
  • "countryCode": "string",
  • "businessPartnerIds": [
    ]
}

Upsert Business Partners

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

SecurityapiKey
Request
path Parameters
storageId
required
string

storageId

Request Body schema: application/json

BusinessPartnersUpsertRequest

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

Batch of business partners

dataSource
string

Data source (name or ID) for all the business partners

featuresOff
Array of strings (UpsertFeatureParam)
Items Enum: "UPSERT_BY_EXTERNAL_ID" "API_ERROR_ON_FAILURES" "LAB_USE_QUEUES" "ENABLE_PRECURATION" "TRANSFORM_RECORD" "ENABLE_SETTINGS" "ENABLE_ASYNC"
featuresOn
Array of strings (UpsertFeatureParam)

Feature(s) to be used during the upsert:

  • 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. When selected, id must not be provided in a business partner.
  • 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.
Items Enum: "UPSERT_BY_EXTERNAL_ID" "API_ERROR_ON_FAILURES" "LAB_USE_QUEUES" "ENABLE_PRECURATION" "TRANSFORM_RECORD" "ENABLE_SETTINGS" "ENABLE_ASYNC"
Responses
200

OK

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