Business Partner Storages

Business Partner Storage Public Webservice

Clear Data Source WSDL

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 Storage WSDL

Remove all Business Partners from given Business Partner Storage.

SecurityapiKey
Request
path Parameters
storageId
required
string

Unique ID of a Business Partner Storage.

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

Unique ID of Business Partner storage.

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.

name
string (BusinessPartnerStorageDataSourceName)

Name of a data source of a storage.

prefix
string (Prefix)

Additional prefix for data source name.

Responses
200

OK

400

Bad Request

post/storages/{storageId}/datasources
Request samples
application/json
{
  • "name": "Internal customers",
  • "dataMapperDefinitionId": "6400955811c68a034bcef311",
  • "prefix": "Custom prefix"
}
Response samples
application/json
{
  • "id": "648824a691d8d2503d65103e",
  • "createdAt": "2020-08-31T16:47+00:00",
  • "lastUpdatedAt": "2020-08-31T16:47+00:00",
  • "name": "Internal customers",
  • "dataMapperDefinitionId": "6400955811c68a034bcef311",
  • "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

storageId

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

List of Data Sources.

description
string (SharingScopeDescription) <= 50 characters

Description of defined sharing scope provided by customer

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.

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"
labels
Array of strings (StorageLabels) <= 10 items unique
name
string (BusinessPartnerStorageName) <= 50 characters

Name of the Business Partner.

sharedWithOrganization
boolean
Default: false

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

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": "2020-08-31T16:47+00:00",
  • "expiresAt": "2019-08-31T16:47+00:00",
  • "dataMatchingDefinitionId": "6400955811c68a034bcef311",
  • "dataSources": [
    ],
  • "updateMonitors": [
    ],
  • "dataMonitors": "[64255349812e8a40bb208a82, 641d8b5594c4330ac2770fea]",
  • "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": [
    ]
}

Create Update Monitor

Create a new update monitor for given storage

SecurityapiKey
Request
path Parameters
storageId
required
string

Unique ID of a storage

Request Body schema: application/json
required
Array of objects (UpdateMonitorDataSource)
affectedProperties
Array of strings (BusinessPartnerPropertyParam)
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" "RECORD"
object (LinkageStrategy)
object (UpdateMonitorReferenceDataSource)

Contains technical key of reference data source.

object (UpdateMonitorStorageDataSource)

The monitored Data Source from this Business Partner Storage. Contains data source id of Business Partner Storage data source.

Responses
200

OK

400

Bad Request

post/v3/storages/{storageId}/updatemonitors
Request samples
application/json
{
  • "affectedDataSources": [
    ],
  • "affectedProperties": [
    ],
  • "referenceDataSource": {
    },
  • "storageDataSource": {
    },
  • "linkageStrategy": {
    }
}
Response samples
application/json
{
  • "id": "bfdfd6f7-562f-4d4a-921f-e68cba60d5cf",
  • "affectedDataSources": [
    ],
  • "affectedProperties": [
    ],
  • "createdAt": "2020-08-31T16:47+00:00",
  • "createdBy": "76248934691294444",
  • "modifiedAt": "2020-08-31T16:47+00:00",
  • "modifiedBy": "76248934691294444",
  • "referenceDataSource": {
    },
  • "storageDataSource": {
    },
  • "linkageStrategy": {
    }
}

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

Unique ID of the data source.

storageId
required
string

Unique ID of the Business Partner storage.

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

Unique ID of a storage

Request Body schema: application/json
required
Array of objects (SharingScopeDelete) <= 1 items
Responses
200

OK

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

Delete Storage WSDL

Delete a Business Partner Storage.

SecurityapiKey
Request
path Parameters
storageId
required
string

Unique ID of a Business Partner Storage.

Responses
200

OK

delete/storages/{storageId}
Request samples

List Data Sources of Update Monitors

List all data sources available for update monitoring.

SecurityapiKey
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

storageId

query Parameters
featuresOn
Array of strings (SharingScopesReadFeatureParam)

Feature(s) to use:

  • FETCH_JOB_DETAILS - Fetch job status and progress. By default off.
Items Value: "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=10
Responses
200

OK

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

List Storages WSDL

List all storages to which user has access to.

SecurityapiKey
Request
query Parameters
dataMapperDefinitionId
Array of strings

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

featuresOn
Array of strings (BusinessPartnerStorageMetadataPageReadFeatureParam)

Features to be turned on:

  • NUMBER_OF_TOTAL - Allows to switch fetching the total number of Business Partners to improve performance. By default turned on.
  • INCLUDE_SHARED_STORAGES - Extend the result with metadata for storages that have been shared by other users of your organization. Alias for includeSharedStorages query parameter. By default turned off.
  • INCLUDE_SHARED_WORKSPACE_STORAGES - Extend the result with metadata for storages that have been shared by other users of your workspace. By default turned off.
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.

label
string

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

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=10
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

Unique ID of a Business Partner Storage.

query Parameters
dataSource
string

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

featuresOn
Array of strings

Feature(s) to be used during reading the metadata:

  • WITH_COUNTRY_STATISTICS - Recalculates and retrieves country statistics information.
  • ONLY_ISO_COUNTRY_STATISTICS - Forces only valid ISO 3166-2 country codes.
Items Enum: "WITH_COUNTRY_STATISTICS" "ONLY_ISO_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": "2020-08-31T16:47+00:00",
  • "expiresAt": "2019-08-31T16:47+00:00",
  • "dataMatchingDefinitionId": "6400955811c68a034bcef311",
  • "dataSources": [
    ],
  • "updateMonitors": [
    ],
  • "dataMonitors": "[64255349812e8a40bb208a82, 641d8b5594c4330ac2770fea]",
  • "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

Unique ID of the data source.

storageId
required
string

Unique ID of the Business Partner storage.

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.

name
string (BusinessPartnerStorageDataSourceName)

Name of a data source of a storage.

prefix
string (Prefix)

Additional prefix for data source name.

Responses
200

OK

400

Bad Request

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

Update Storage

Update a Business Partner Storage.

SecurityapiKey
Request
path Parameters
storageId
required
string

Unique ID of a Business Partner Storage.

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.

labels
Array of strings (StorageLabels) <= 10 items unique

List of Storages labels.

name
string <= 50 characters

Name of the Business Partner Storage.

sharedWithOrganization
boolean (SharedWithOrganization)

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

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": "2020-08-31T16:47+00:00",
  • "expiresAt": "2019-08-31T16:47+00:00",
  • "dataMatchingDefinitionId": "6400955811c68a034bcef311",
  • "dataSources": [
    ],
  • "updateMonitors": [
    ],
  • "dataMonitors": "[64255349812e8a40bb208a82, 641d8b5594c4330ac2770fea]",
  • "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": [
    ]
}