Business Partners

Delete Business PartnersWSDL

Delete batches of Business Partners by ID or a combination of DataSource and External ID. Maximum of 1000 Business Partners are allowed per batch. In case only a data source is provided in the request, all Business Partners related to this data source will be deleted, but the data source itself will not be deleted.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

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

cmd

Array of objects <= 1000 items

List of Business Partners to be deleted.

dataSource
string (BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

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

List of features to be used during delete.

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

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

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

List Business PartnersDeprecated

Deprecated. Please use higher versions.

Read a page of Business Partners from the storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
query Parameters
countryCode
Array of strings (CountryShortName)

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

Example: countryCode=CH
dataSource
string (BusinessPartnerDataSource)

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

Example: dataSource="CUSTOM_DATA_SOURCE" or "648824a691d8d2503d65103e"
dataSourceId
Array of strings (BusinessPartnerStorageDataSourceId)

Filter by specified Data Source ID.

Example: dataSourceId=648824a691d8d2503d65103e
page
integer <int32> >= 0
Default: 0

Number of the page that will be retrieved.

Example: page=10
pageSize
integer <int32> >= 1
Default: 20

Number of items to be returned on the page.

Example: pageSize=10
Responses
200

OK

get/storages/{storageId}/businesspartners
Request samples
Response samples
application/json
{
  • "numberOfPages": "10",
  • "page": "1",
  • "pageSize": "100",
  • "total": "67",
  • "values": [
    ]
}

Lookup Business PartnerWSDL

Lookup a Business Partner in provided storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

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

cmd

required
object

An organization which has some degree of involvement with another organization's business dealings. Typically, a company's business partner is another company in the role of a customer, a supplier, a vendor, or a service provider. In the CDL context, the business partner is the core managed entity. A business partner is globally uniquely identifiable by a CDL ID, and all managed information such as addresses, documents, and hierarchies is linked to a business partner.

Responses
200

OK

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

post/storages/{storageId}/businesspartners/lookup
Request samples
application/json
{
  • "businessPartner": {
    }
}
Response samples
application/json
{
  • "pageSize": "100",
  • "totals": "67",
  • "page": "1",
  • "values": [
    ]
}

Poll Toggle Update Monitoring Job

Poll endpoint for a job created in POST toggleUpdateMonitoringJobs.

SecurityapiKey
Request
path Parameters
jobId
required
string (JobId)

Unique identifier of a job.

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

OK

get/jobs/toggleUpdateMonitoringJobs/{jobId}
Request samples
Response samples
application/json
{
  • "job": {
    },
  • "status": "OK"
}

Read Business PartnerDeprecated

Deprecated. Please use higher versions.

Read a single Business Partner from the storage.

SecurityapiKey
Request
path Parameters
id
required
string (BusinessPartnerId)

Unique identifier of the Business Partner.

Example: 63e635235c06b7396330fe40
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Responses
200

OK

get/storages/{storageId}/businesspartners/{id}
Request samples
Response samples
application/json
{
  • "id": "63e635235c06b7396330fe40",
  • "disclosed": "false",
  • "names": [
    ],
  • "legalForm": "Aktiengesellschaft",
  • "identifiers": [
    ],
  • "categories": [
    ],
  • "classifications": [
    ],
  • "companyStatus": "ACTIVE",
  • "status": {
    },
  • "results": {
    },
  • "addresses": [
    ],
  • "externalId": "The ID managed in the customer's SAP systems.",
  • "dataSource": "\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\"",
  • "record": "{\"name\": \"BUSINESSPARTNER_NAME\", ...}"
}

Start a Toggle Update Monitoring Job

To toggle update monitoring on multiple BusinessPartners, the permission can be changed in two ways:

  1. A complete Data Source identified by the parameter 'dataSourceId'
  2. 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 non-commercial reference data sources are removed
    • updates are no more propagated for this Business Partner
    • linkage is not performed for any non-commercial reference data source

For toggling via a list of Business Partners, identified by their ID, please go to Toggle Update Monitoring of Business Partners.

SecurityapiKey
Request
Request Body schema: application/json
required
countryShortName
string (CountryShortName)

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

Example: "CH"
dataSourceId
required
string (BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
description
string (JobDescription)

Detailed description of a Job.

Example: "I started this job to improve quality of our data."
enable
required
boolean (ToggleUpdateMonitoringRequestEnable)

Parameter to describe if the Business Partners should be activated for update monitoring (true) or deactivated (false) for non-commercial reference data sources.

Example: "true"
name
string (JobName)

Name of a Job.

Example: "Process vendor data."
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"
Responses
200

OK

400

The sent request is malformed.

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

Toggle Business Partners Update Monitoring

To toggle update monitoring on multiple BusinessPartners, the permission can be changed via a list of Business Partners, identified by their ID.

After the job is finished, the following actions are taken for Business Partners which match the businessPartnerIds criteria:

  • businessPartner.updateMonitoring fields takes a value of ToggleUpdateMonitoringJobRequest#enable
  • if enable is true then:
  • if enable is false then:
    • all existing links of a Business Partner to Business Partners in non-commercial reference data sources are removed
    • updates are no more propagated for this Business Partner
    • linkage is not performed for any non-commercial reference data source

For toggling a complete Data Source or for a certain Country of a Data Source, please go to Start Toggle Update Monitoring Job.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
businessPartnerIds
required
Array of strings (BusinessPartnerId) [ 1 .. 1000 ] items

List of Business Partner IDs to identify all those Business Partners that should be activated/deactivated.

Example: ["63e635235c06b7396330fe40"]
enable
required
boolean (ToggleUpdateMonitoringRequestEnable)

Parameter to describe if the Business Partners should be activated for update monitoring (true) or deactivated (false) for non-commercial reference data sources.

Example: "true"
Responses
204

OK

put/storages/{storageId}/businesspartners/toggleUpdateMonitoring
Request samples
application/json
{
  • "enable": "true",
  • "businessPartnerIds": [
    ]
}

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, 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\"}",
     "names": [
       {
         "value": "CDQ AG",
         "type": "BUSINESS_PARTNER_NAME_TYPE_LOCAL"
       }
     ],
     "addresses": [{
       "thoroughfare": {
         "value": "Lukasstrasse 4"
       },
       "postCode": {
         "value": "9008"
       },
       "locality": {
         "value": "St. Gallen"
       },
       "country": {
         "shortname": "CH"
       }
     }]
   }]
}'

The response is shown below.

{
   "numberOfInserts": "1",
   "numberOfUpdates": "0",
}

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[].addresses[].context 100
$.businessPartners[].addresses[].addressTypes 20
SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

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

Request to create or update business partners.

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

List of Business Partners.

dataSource
string (BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"
featuresOff
Array of strings (UpsertFeature)

Features to be deactivated during the upsert.

Items Enum: Description
UPSERT_BY_EXTERNAL_ID

Updates Business Partners identified by external ID instead of an insert if the external ID is already present in this Business Partner Storage.

API_ERROR_ON_FAILURES

Throws exception instead of default Upsert Failure Log.

TRANSFORM_RECORD

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

ENABLE_SETTINGS

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

ENABLE_ASYNC

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

Example: ["UPSERT_BY_EXTERNAL_ID"]
featuresOn
Array of strings (UpsertFeature)

Features to be activated during the upsert.

Items Enum: Description
UPSERT_BY_EXTERNAL_ID

Updates Business Partners identified by external ID instead of an insert if the external ID is already present in this Business Partner Storage.

API_ERROR_ON_FAILURES

Throws exception instead of default Upsert Failure Log.

TRANSFORM_RECORD

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

ENABLE_SETTINGS

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

ENABLE_ASYNC

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

Example: ["UPSERT_BY_EXTERNAL_ID"]
Responses
200

OK

400

The sent request is malformed.

401

Invalid authentication was sent.

put/storages/{storageId}/businesspartners
Request samples
application/json
{
  • "dataSource": "648824a691d8d2503d65103e",
  • "businessPartners": [
    ],
  • "featuresOn": [
    ],
  • "featuresOff": [
    ]
}
Response samples
application/json
{
  • "id": "648824a691d8d2503d65103e",
  • "name": "Internal customers",
  • "eventStoreId": "72d6900fce6b326123f5d9d91049e3e6",
  • "domain": "BusinessPartner",
  • "organization": "cdq_monitor",
  • "user": "johndoe",
  • "createdAt": "2024-11-22T13:20:20Z",
  • "expiresAt": "2024-11-22T13:20:20Z",
  • "dataMatchingDefinitionId": "6400955811c68a034bcef311",
  • "dataSources": [
    ],
  • "dataMonitors": [
    ],
  • "features": {
    },
  • "numberOfCountries": "12",
  • "numberOfRecords": "500",
  • "countryStatistics": [
    ],
  • "originalFileHeader": [
    ],
  • "originalFileName": "business-partner.csv",
  • "results": {
    },
  • "status": "FILE_IMPORTED_SUCCESSFULLY",
  • "statusMessage": "BusinessPartner batch could not be upserted into Business Partner Storage.",
  • "sharedWithOrganization": "true",
  • "labels": [
    ]
}