Business Partner Storages

Business Partner Storage Public Webservice

Clear Data SourceWSDL

Clear all Business Partners of a data source.

SecurityapiKey
Request
path Parameters
dataSourceId
required
string (BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: 648824a691d8d2503d65103e
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Responses
200

OK

post/storages/{storageId}/datasources/{dataSourceId}/clear
Request samples
Response samples
application/json
{
  • "numberOfDeletes": "50",
  • "numberOfFailures": "0",
  • "failures": [
    ]
}

Clear StorageWSDL

Remove all Business Partners from given Business Partner Storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique ID of a Business Partner Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Responses
200

OK

post/storages/{storageId}/clear
Request samples
Response samples
application/json
{
  • "numberOfDeletes": "50"
}

Create Data Source

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

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique ID of Business Partner storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
dataMapperDefinitionId
string (DataMapperDefinitionId)

ID of related Data Mapper Definition that is used for mapping data of this Business Partner Storage.

Example: "6440dba32b30176c5917b1b7"
name
string (BusinessPartnerStorageDataSourceName)

Name of a data source of a storage.

Example: "Internal customers"
prefix
string (Prefix)

Additional prefix for data source name.

Example: "Custom prefix"
Responses
200

OK

400

Bad Request

post/storages/{storageId}/datasources
Request samples
application/json
{
  • "name": "Internal customers",
  • "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
  • "prefix": "Custom prefix"
}
Response samples
application/json
{
  • "id": "648824a691d8d2503d65103e",
  • "createdAt": "2024-05-21T11:45:12Z",
  • "lastUpdatedAt": "2024-05-21T11:45:12Z",
  • "name": "Internal customers",
  • "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
  • "prefix": "Custom prefix"
}

Create Sharing Scope

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 disclosure of a concrete Business Partner, it has to be requested directly.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
Array of objects (SharingScopeCountryParam) <= 1 items

List of Countries.

Array of objects (BusinessPartnerStorageDataSourceParam) <= 1 items

List of Data Sources.

description
string (SharingScopeDescription) <= 50 characters

Description of defined sharing scope provided by customer

Example: "Share customers from France."
Responses
200

OK

400

Bad Request

post/v4/storages/{storageId}/sharingscopes
Request samples
application/json
{
  • "description": "Share customers from France.",
  • "dataSources": [
    ],
  • "countries": [
    ]
}
Response samples
application/json
{
  • "id": "bfdfd6f7-562f-4d4a-921f-e68cba60d5cf",
  • "description": "Share customers from France.",
  • "dataSources": [
    ],
  • "countries": [
    ],
  • "applyingJob": {
    }
}

Create Storage

If no data source is provided, a minimal data source (name=default and without mapping ID) is attached.

SecurityapiKey
Request
Request Body schema: application/json
dataMatchingDefinitionId
string (DataMatchingDefinitionId)

ID of related data matching definition that is used for matching lookup candidates for internal lookup of this Business Partner Storage.

Example: "6400955811c68a034bcef311"
Array of objects

List of Data Sources.

featuresOn
Array of strings
Items Enum: "LOOKUP" "UPDATES" "LAB_USE_INDEX_API" "SHARING" "DATA_MIRROR" "HOMELAND" "NEVER_EXPIRE" "RELATIONS"
Example: ["LOOKUP"]
labels
Array of strings (StorageLabels) <= 10 items unique
Example: ["Custom Storage Name"]
name
string (BusinessPartnerStorageName) <= 50 characters

Name of the Business Partner.

Example: "Bosch AG"
sharedWithOrganization
boolean
Default: false

Indicates if this storage is shared with all users of the same organization.

Example: "false"
Responses
200

OK

400

The sent request is malformed.

post/v2/storages
Request samples
application/json
{
  • "name": "string",
  • "dataMatchingDefinitionId": "string",
  • "dataSources": [
    ],
  • "featuresOn": [
    ],
  • "sharedWithOrganization": false,
  • "labels": [
    ]
}
Response samples
application/json
{
  • "id": "648824a691d8d2503d65103e",
  • "name": "Internal customers",
  • "eventStoreId": "72d6900fce6b326123f5d9d91049e3e6",
  • "decisionLogId": "72d6900fc3wb326088f5d9d91044e3e6",
  • "domain": "BusinessPartner",
  • "organization": "cdq_monitor",
  • "user": "johndoe",
  • "createdAt": "2024-05-21T11:45:12Z",
  • "expiresAt": "2024-05-21T11:45:12Z",
  • "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": [
    ]
}

Delete Data Source

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).
SecurityapiKey
Request
path Parameters
dataSourceId
required
string (BusinessPartnerStorageDataSourceId)

Filter by specified Data Source ID.

Example: 648824a691d8d2503d65103e
storageId
required
string (BusinessPartnerStorageId)

Unique ID of the Business Partner storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Responses
200

OK

delete/storages/{storageId}/datasources/{dataSourceId}
Request samples

Delete Sharing Scopes

Delete sharing scopes. When deleting sharing scope, all Business Partners from selection scope who are not included in any other sharing scopes, become undisclosed.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
Array of objects (SharingScopeDelete) <= 1 items

List of Sharing Scopes to be deleted.

Responses
200

OK

post/v4/storages/{storageId}/sharingscopes/delete
Request samples
application/json
{
  • "sharingScopes": [
    ]
}
Response samples
application/json
{
  • "sharingScopes": [
    ]
}

Delete StorageWSDL

Delete a Business Partner Storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique ID of a Business Partner Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Responses
200

OK

delete/storages/{storageId}
Request samples

List Data Sources of Update Monitors

List all data sources available for update monitoring.

SecurityapiKey
Request
query Parameters
featuresOn
Array of strings (UpdateMonitoringReferenceDataSourcesReadFeatureParam)

Features to be activated.

Items Value: Description
FETCH_ACTIVATION_STATUS

Returns information which data source is inactive for the organization.

Example: featuresOn=FETCH_ACTIVATION_STATUS
Responses
200

OK

get/v2/updatemonitors/referencedatasources
Request samples
Response samples
application/json
{
  • "referenceDataSources": [
    ]
}

List Sharing Scopes

List all sharing scopes of the give storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
query Parameters
featuresOn
Array of strings (SharingScopesReadFeatureParam)

Features to be activated.

Items Value: Description
FETCH_JOB_DETAILS

Fetch job status and progress. By default, off.

Example: featuresOn=FETCH_JOB_DETAILS
limit
integer <int32> >= 1
Default: 500

Number of items to be returned on the page.

Example: limit=100
startAfter
string

Only items with an ID greater than the given one will be retrieved.

When nextStartAfter provided in the response, should be used instead of the ID as an indicator for a next page.

Example: startAfter=5712566172571652
Responses
200

OK

get/v4/storages/{storageId}/sharingscopes
Request samples
Response samples
application/json
{
  • "values": [
    ],
  • "limit": "100",
  • "startAfter": "5712566172571652",
  • "nextStartAfter": "5712566172571652",
  • "total": "67"
}

List StoragesWSDL

List all storages to which user has access to.

SecurityapiKey
Request
query Parameters
dataMapperDefinitionId
Array of strings (DataMapperDefinitionId)

Filter the result and Data Sources by Data Mapper Definition ID.

Example: dataMapperDefinitionId=6440dba32b30176c5917b1b7
featuresOn
Array of strings (BusinessPartnerStorageMetadataPageReadFeatureParam)

Features to be activated.

Items Enum: Description
NUMBER_OF_TOTAL

Returns the total number of storages.

INCLUDE_SHARED_STORAGES

Returns the shared storages.

INCLUDE_SHARED_WORKSPACE_STORAGES

Returns the shared workspace storages.

Example: featuresOn=NUMBER_OF_TOTAL
includeSharedStorages
boolean
Default: false

Optionally extend the result with metadata for storages that have been shared by other users of your organization. Alias for INCLUDE_SHARED_STORAGES feature.

Example: includeSharedStorages=true
label
string

Filter the result by the given label. Keep in mind that labels are case-sensitive.

Example: label=My Storage
limit
integer <int32> >= 1
Default: 500

Number of items to be returned on the page.

Example: limit=100
sort
string

Defines the attributes to sort by. Supported attributes are 'id', 'name' and 'createdAt', separated by comma (,) and the sort direction in front of each attribute. '+' means ascending, '-' means descending. Default sort, if direction is not given, is ascending.

Example: sort=-createdAt
startAfter
string

Only items with an ID greater than the given one will be retrieved.

When nextStartAfter provided in the response, should be used instead of the ID as an indicator for a next page.

Example: startAfter=5712566172571652
Responses
200

OK

get/v2/storages
Request samples
Response samples
application/json
{
  • "values": [
    ],
  • "limit": "100",
  • "startAfter": "5712566172571652",
  • "nextStartAfter": "5712566172571652",
  • "total": "67"
}

Read Storage

Read metadata of a storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique ID of a Business Partner Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
query Parameters
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"
featuresOn
Array of strings

Features to be activated during reading the metadata.

Items Enum: Description
WITH_COUNTRY_STATISTICS

Recalculates and retrieves country statistics information.

ONLY_ISO_COUNTRY_STATISTICS

Forces only valid ISO 3166-2 country codes.

Example: featuresOn=WITH_COUNTRY_STATISTICS
Responses
200

OK

get/v2/storages/{storageId}
Request samples
Response samples
application/json
{
  • "id": "648824a691d8d2503d65103e",
  • "name": "Internal customers",
  • "eventStoreId": "72d6900fce6b326123f5d9d91049e3e6",
  • "decisionLogId": "72d6900fc3wb326088f5d9d91044e3e6",
  • "domain": "BusinessPartner",
  • "organization": "cdq_monitor",
  • "user": "johndoe",
  • "createdAt": "2024-05-21T11:45:12Z",
  • "expiresAt": "2024-05-21T11:45:12Z",
  • "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": [
    ]
}

Update Data Source

Update a Data Source.

SecurityapiKey
Request
path Parameters
dataSourceId
required
string (BusinessPartnerStorageDataSourceId)

Filter by specified Data Source ID.

Example: 648824a691d8d2503d65103e
storageId
required
string (BusinessPartnerStorageId)

Unique ID of the Business Partner storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
dataMapperDefinitionId
string (DataMapperDefinitionId)

ID of related Data Mapper Definition that is used for mapping data of this Business Partner Storage.

Example: "6440dba32b30176c5917b1b7"
name
string (BusinessPartnerStorageDataSourceName)

Name of a data source of a storage.

Example: "Internal customers"
prefix
string (Prefix)

Additional prefix for data source name.

Example: "Custom prefix"
Responses
200

OK

400

Bad Request

put/storages/{storageId}/datasources/{dataSourceId}
Request samples
application/json
{
  • "name": "Internal customers",
  • "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
  • "prefix": "Custom prefix"
}
Response samples
application/json
{
  • "dataSource": {
    },
  • "status": "OK"
}

Update Storage

Update a Business Partner Storage.

SecurityapiKey
Request
path Parameters
storageId
required
string (BusinessPartnerStorageId)

Unique ID of a Business Partner Storage.

Example: 72d6900fce6b326088f5d9d91049e3e6
Request Body schema: application/json
required
dataMatchingDefinitionId
string (DataMatchingDefinitionId)

ID of related data matching definition that is used for matching lookup candidates for internal lookup of this Business Partner Storage.

Example: "6400955811c68a034bcef311"
labels
Array of strings (StorageLabels) <= 10 items unique

List of Storages labels.

Example: ["Custom Storage Name"]
name
string <= 50 characters

Name of the Business Partner Storage.

Example: "My Storage"
sharedWithOrganization
boolean (SharedWithOrganization)

Indicates if this Business Partner Storage is shared with all users of the same organization

Example: "true"
Responses
200

OK

put/storages/{storageId}
Request samples
application/json
{
  • "name": "My Storage",
  • "labels": [
    ],
  • "dataMatchingDefinitionId": "6400955811c68a034bcef311",
  • "sharedWithOrganization": "true"
}
Response samples
application/json
{
  • "id": "648824a691d8d2503d65103e",
  • "name": "Internal customers",
  • "eventStoreId": "72d6900fce6b326123f5d9d91049e3e6",
  • "decisionLogId": "72d6900fc3wb326088f5d9d91044e3e6",
  • "domain": "BusinessPartner",
  • "organization": "cdq_monitor",
  • "user": "johndoe",
  • "createdAt": "2024-05-21T11:45:12Z",
  • "expiresAt": "2024-05-21T11:45:12Z",
  • "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": [
    ]
}