Skip to content

Data Exchange API (5)

This API provides services to upload, manipulate and download businesspartner data in the CDL Cloud.

Overview
URL

https://www.cdq.ch/team

Michal Malinka

michal.malinka@cdq.ch

Languages
Servers
Mock server

https://idp.cdq.com/_mock/apis/data-exchange-api/api-v5/

Production SOAP

https://api.corporate-data-league.ch/data-exchange/soap/v5/

Production

https://api.corporate-data-league.ch/data-exchange/

Seed Updates

Manages operations such as creating, updating, or transforming Business Partner data to ensure that the information is current and accurate.

Operations

Analytics

Provides functionalities for analyzing and processing Business Partner data, enabling users to gain insights and perform various analytical operations on the data.

Business Partner Storages

Provides functionalities for creating, retrieving, updating and deleting Business Partner storage, as well as managing associated data sources and data monitors.

Operations

Business Partners

Provides functionalities for creating, retrieving, updating, and deleting Business Partner records, as well as performing various operations such as lookup and upsert.

Operations

Create Business Partner

Request

Create a Business Partner in the community pool. Goal - receive back the full Business Partner.

Security
basicAuth
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired
businessPartnerobject(BusinessPartner)

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.

curl -i -X POST \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-exchange-api/api-v5/v4/cdqpool/businesspartners \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "businessPartner": {
      "id": "63e635235c06b7396330fe40",
      "createdAt": "2020-08-31T16:47+00:00",
      "modifiedAt": "2020-08-31T16:47+00:00",
      "externalId": "The ID managed in the customer'\''s SAP systems.",
      "dataSource": "\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\"",
      "disclosed": "false",
      "updateMonitoring": "true",
      "updateCommercialMonitoring": [
        {
          "type": {
            "technicalKey": "DNB"
          },
          "value": "true"
        }
      ],
      "metadata": {
        "lastUpdatedAt": "2020-08-31T16:47+00:00",
        "lastSyncAt": "2020-02-11T00:00:00Z",
        "sharingStatus": {
          "status": "SHARED_WITH_NO_MATCH",
          "description": "UNDER_CONSIDERATION: The business partner will be considered for the sharing process."
        },
        "identityLinks": [
          {
            "linkId": "6465f2492bdcd350159a79d6",
            "cdqId": "VIES:PL8660001429",
            "addressId": "0",
            "externalAddressId": "123456789",
            "status": {
              "details": [
                {}
              ]
            }
          }
        ],
        "logResultStatuses": [
          {
            "processingLogId": "CURATION_LOG",
            "triggerProcessedAt": "2020-08-31T16:47+00:00",
            "triggerType": {
              "name": "CREATED",
              "technicalKey": "CREATED"
            },
            "trigger": {
              "processedAt": "2020-08-31T16:47+00:00",
              "provenance": {
                "name": "VIES",
                "technicalKey": "VIES",
                "cdqId": "VIES:PL8660001429"
              },
              "type": {
                "name": "CREATED",
                "technicalKey": "CREATED"
              }
            },
            "jobProcessedAt": "2020-08-31T16:47+00:00",
            "processedAt": "2020-08-31T16:47+00:00",
            "status": "INFO",
            "description": "Validation Level",
            "processingStatus": {
              "technicalKey": "IN_PROGRESS",
              "modifiedAt": "2020-08-31T16:47+00:00"
            },
            "previousProcessingStatus": {
              "technicalKey": "IN_PROGRESS",
              "modifiedAt": "2020-08-31T16:47+00:00"
            }
          }
        ],
        "decisionLogResult": {
          "reviewStatus": "REVIEWED",
          "naturalPersonsReviewStatus": "REVIEWED",
          "duplicatesReviewStatus": "REVIEWED"
        }
      },
      "record": "{\"name\": \"BUSINESSPARTNER_NAME\", ...}",
      "additionalInformation": [
        {
          "key": "KEY",
          "value": "1"
        }
      ],
      "names": [
        {
          "type": {
            "url": "https://meta.cdq.com/Business_partner/name/type",
            "name": "Local Name",
            "technicalKey": "LOCAL"
          },
          "value": "Corporate Data Quality AG",
          "shortName": "CDQ AG",
          "language": {
            "name": "German",
            "technicalKey": "DE"
          },
          "details": [
            {
              "value": "Corporate Data Quality AG - Marketing Department",
              "type": {
                "name": "Legal Entity",
                "url": "https://meta.cdq.com/Business_partner/type",
                "technicalKey": "LEGAL_ENTITY"
              }
            }
          ]
        }
      ],
      "legalForm": {
        "name": "Aktiengesellschaft",
        "url": "https://meta.cdq.com/Business_partner/legal_form",
        "technicalKey": "DE_9866",
        "language": {
          "name": "German",
          "technicalKey": "DE"
        },
        "mainAbbreviation": "AG",
        "categories": [
          {
            "name": "Limited Liability Company",
            "shortName": "LLC",
            "url": "https://meta.cdq.com/Business_partner/legal_form/category/technical_key/LF001",
            "technicalKey": "LIMITED"
          }
        ]
      },
      "identifiers": [
        {
          "type": {
            "url": "https://meta.cdq.com/Business_partner/identifier/type",
            "name": "CH_VAT_ID",
            "technicalKey": "CH_VAT_ID"
          },
          "value": "CHE-218.608.886 HR/MWST",
          "issuingBody": {
            "name": "Amtsgericht Aachen",
            "url": "https://meta.cdq.com/Business_partner/identifier/issuing_body",
            "technicalKey": "Amtsgericht Aachen",
            "jurisdiction": {
              "country": {
                "shortName": "CH",
                "value": "Switzerland"
              }
            }
          },
          "status": {
            "name": "ACTIVE",
            "technicalKey": "ACTIVE"
          }
        }
      ],
      "categories": [
        {
          "name": "Hotel",
          "url": "https://meta.cdq.com/Business_partner/category",
          "technicalKey": "HOTEL"
        }
      ],
      "status": {
        "type": {
          "name": "In Liquidation",
          "url": "https://meta.cdq.com/Business_partner/status/type",
          "technicalKey": "IN_LIQUIDATION"
        },
        "officialDenotation": "Good Standing",
        "validFrom": "2022-02-26",
        "validUntil": "2022-02-26"
      },
      "profile": {
        "minorityIndicator": {
          "value": "Social enterprise"
        },
        "classifications": [
          {
            "value": "Manufacture of pesticides and other agrochemical products.",
            "code": "20.20Z",
            "type": {
              "name": "NAF 2003",
              "url": "https://meta.cdq.com/Business_partner/partner_profile/classification/type",
              "technicalKey": "NAF_2003"
            }
          }
        ],
        "phoneNumbers": [
          {
            "countryPrefix": "+41",
            "number": "71 571 10 40",
            "type": {
              "name": "FAX",
              "url": "https://meta.cdq.com/Business_partner/partner_profile/phone_number/type",
              "technicalKey": "FAX"
            },
            "value": "+41 71 571 10 40"
          }
        ],
        "websites": [
          {
            "url": "https://cdq.com",
            "type": {
              "name": "Corporate Website",
              "url": "https://meta.cdq.com/Business_Partner/partner_profile/website/type",
              "technicalKey": "WEBSITE_TYPE_CORPORATE"
            }
          }
        ],
        "contactEmails": [
          {
            "value": "developer-portal@cdq.com"
          }
        ],
        "tags": [
          {
            "value": "Warehouse",
            "type": {
              "technicalKey": "WAREHOUSE"
            }
          }
        ],
        "vatPayerStatus": {
          "publicationDate": "2020-07-21T17:32:28Z",
          "status": {
            "name": "RELIABLE",
            "technicalKey": "VAT_PAYER_STATUS"
          },
          "registrationAuthority": {
            "registrationAuthorityId": "RA000009",
            "registrationAuthorityEntityId": "RA000009",
            "otherRegistrationAuthorityId": "RA000009"
          }
        },
        "hcpProfile": {
          "generalLicense": {
            "professionType": {
              "name": "Doctor",
              "url": "https://meta.cdq.com/Business_partner/partner_profile/hcp_profile/general_license/profession_type/technical_key",
              "technicalKey": "DOCTOR"
            },
            "licenseStatus": {
              "name": "Granted",
              "url": "https://meta.cdq.com/Business_partner/partner_profile/hcp_profile/general_license/license_status/technical_key",
              "technicalKey": "GRANTED"
            }
          },
          "operationalPermissions": [
            {
              "issuingAuthority": "Swiss Medical Association",
              "permissionStatus": {
                "name": "Granted",
                "url": "https://meta.cdq.com/Business_partner/partner_profile/hcp_profile/operational_permissions/permission_status/url",
                "technicalKey": "GRANTED"
              },
              "activityStatus": {
                "name": "Inactive",
                "url": "https://meta.cdq.com/Business_partner/partner_profile/hcp_profile/operational_permissions/activity_status/url",
                "technicalKey": "INACTIVE"
              },
              "practiceLocations": [
                {}
              ]
            }
          ]
        }
      },
      "relations": [
        {
          "startedAt": "2019-08-31T16:47+00:00",
          "endedAt": "2019-08-31T16:47+00:00",
          "type": {
            "name": "Commercial ultimate",
            "technicalKey": "COMMERCIAL_ULTIMATE",
            "url": "https://meta.cdq.com/Business_partner/relation/type"
          },
          "class": {
            "name": "CDQ Hierarchy",
            "technicalKey": "BUSINESS_PARTNER_RELATION_CLASS_CDQ_HIERARCHY",
            "url": "https://meta.cdq.com/Business_partner/relation/class"
          },
          "startNode": {
            "externalId": "The ID managed in the customer'\''s SAP systems.",
            "dataSourceId": "648824a691d8d2503d65103e"
          },
          "endNode": {
            "externalId": "The ID managed in the customer'\''s SAP systems.",
            "dataSourceId": "648824a691d8d2503d65103e"
          },
          "deactivatedAt": "2019-08-31T16:47+00:00"
        }
      ],
      "types": [
        {
          "name": "Legal Entity",
          "url": "https://meta.cdq.com/Business_partner/type",
          "technicalKey": "LEGAL_ENTITY"
        }
      ],
      "addresses": [
        {
          "id": "0001",
          "externalId": "1",
          "cdqId": "CDQID-123456789",
          "version": {
            "language": {
              "name": "German",
              "technicalKey": "DE"
            },
            "characterSet": {
              "name": "International",
              "technicalKey": "INTERNATIONAL"
            }
          },
          "identifyingName": {
            "value": "John Doe"
          },
          "careOf": {
            "value": "CDQ GmbH c/o Product Department"
          },
          "contexts": [
            {
              "value": "Production hall 7, Storage field 8."
            }
          ],
          "country": {
            "shortName": "CH",
            "value": "Switzerland"
          },
          "administrativeAreas": [
            {
              "value": "Sankt Gallen",
              "shortName": "SG",
              "isoCode": "CH-SG",
              "type": {
                "name": "COUNTY",
                "url": "https://meta.cdq.com/Address/administrative_area/type",
                "technicalKey": "COUNTY"
              },
              "language": {
                "name": "German",
                "technicalKey": "DE"
              }
            }
          ],
          "postCodes": [
            {
              "value": "9000",
              "type": {
                "name": "Regular",
                "url": "https://meta.cdq.com/Address/post_code/type",
                "technicalKey": "REGULAR"
              }
            }
          ],
          "localities": [
            {
              "type": {
                "name": "City",
                "url": "https://meta.cdq.com/Address/locality/type",
                "technicalKey": "CITY"
              },
              "shortName": "St. Gallen",
              "value": "Sankt Gallen",
              "language": {
                "name": "German",
                "technicalKey": "DE"
              }
            }
          ],
          "thoroughfares": [
            {
              "type": {
                "name": "Industrial zone",
                "url": "https://meta.cdq.com/Address/thoroughfare/type",
                "technicalKey": "INDUSTRIAL_ZONE"
              },
              "shortName": "Lukasstr. 4",
              "number": "4",
              "value": "Lukasstraße 4",
              "name": "Lukasstraße",
              "direction": "221-bis Baker Street, North",
              "language": {
                "name": "German",
                "technicalKey": "DE"
              }
            }
          ],
          "premises": [
            {
              "value": "Lukasstraße 4",
              "shortName": "Lukasstr. 4",
              "number": "4",
              "type": {
                "name": "Factory",
                "url": "https://meta.cdq.com/Address/premise/type",
                "technicalKey": "FACTORY"
              },
              "language": {
                "name": "German",
                "technicalKey": "DE"
              }
            }
          ],
          "postalDeliveryPoints": [
            {
              "type": {
                "name": "Mailbox",
                "url": "https://meta.cdq.com/Address/postal_delivery_point/type",
                "technicalKey": "MAILBOX"
              },
              "shortName": "St Gallen, Postfach 460",
              "number": "460",
              "value": "Postfach",
              "language": {
                "name": "German",
                "technicalKey": "DE"
              }
            }
          ],
          "geographicCoordinates": {
            "latitude": "47.439549",
            "longitude": "9.395275"
          },
          "types": [
            {
              "name": "Legal Address",
              "url": "https://meta.cdq.com/Address/type",
              "technicalKey": "LEGAL_ADDRESS"
            }
          ]
        }
      ],
      "bankAccounts": [
        {
          "internationalBankAccountIdentifier": "CH8800781619278412000",
          "internationalBankIdentifier": "KBSGCH22XXX",
          "nationalBankAccountIdentifier": "619278412000",
          "nationalBankIdentifier": "00781",
          "countryCode": "DE",
          "vendorPaymentSummary": {
            "firstPaymentDate": "2020-08-31T16:47+00:00",
            "lastPaymentDate": "2020-08-31T16:47+00:00",
            "numberOfPayments": "1"
          }
        }
      ],
      "externalContext": {
        "identifiers": [
          {
            "value": "7250017031",
            "type": {
              "technicalKey": "KUNNR"
            }
          }
        ]
      }
    }
  }'

Responses

OK

Bodyapplication/json
idstring(BusinessPartnerId)

A CDQ ID identifies a business partner uniquely in the context of the Corporate Data League.

Example: "63e635235c06b7396330fe40"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
externalIdstring(BusinessPartnerExternalId)

Arbitrary identifier type to mark customer IDs that are "external" from CDQ's perspective. This is the identifier a customer provides to identify its records.

Example: "The ID managed in the customer's SAP systems."
dataSourcestring(BusinessPartnerDataSource)

Name or ID of a data source. Reflects the associated external system where the record originates from.

Example: "\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\""
disclosedboolean(BusinessPartnerDisclosed)

A flag to indicate whether the Business Partner should participate in the sharing or not. If 'true' this Business Partner might be used to create a new entry or update an existing entry in the community pool. Otherwise, it will not be considered for the sharing process. For more details, you can read about Sharing Scopes.

Example: "false"
updateMonitoringboolean(BusinessPartnerUpdateMonitoring)

A flag to indicate whether the Business Partner should receive updates from non-commercial Reference Data Sources or not. If 'true' this Business Partner will receive updates since the change from 'false'. If 'false' this Business Partner will not receive any new updates since the change. If not provided, the previous value will not be changed. By default, Update Monitoring is activated.

Example: "true"
updateCommercialMonitoringArray of objects(BusinessPartnerUpdateCommercialMonitoring)

Enabling update commercial monitoring has 2 possibilities:

  • via Data Mapper Definition: include mapping of updateCommercialMonitoring in the Data Mapper Definition
  • via direct Business Partner model upload: fill complete Business Partner model and updateCommercialMonitoring. Null/undefined updateCommercialMonitoring results in protection of this setup from the previous upsert. Empty or filled updateCommercialMonitoring results in data transition that may link or unlink to / from respective commercial Reference Data Source

Note: follow the approach that is currently used in your storage integration.

metadataobject(BusinessPartnerMetadata)

Information about results of Business Partner processing.

recordstring(BusinessPartnerRecord)

Stringified JSON of an individual Business Partner record. Characters: backslash \ and double quote " must be escaped (respectively: \\\\ and \"). Fields containing . are unallowed. Maximum size: 15MB.

Example: "{\"name\": \"BUSINESSPARTNER_NAME\", ...}"
additionalInformationArray of objects(AdditionalInformation)

List of additional information.

namesArray of objects(Name)

List of names.

legalFormobject(LegalForm)

The legal form of a business partner/type/legal entity is the form it takes in the eyes of the law governing it. The legal form of a company is the general type it may legally use to identify itself according to the local, regional, national, or international law governing it. This is normally reflected in the ending abbreviation after the company's name (e.g. AG, Inc., LLC, S.A.).

identifiersArray of objects(Identifier)

List of Identifiers.

categoriesArray of objects(BusinessPartnerCategory)

List of Categories.

statusobject(BusinessPartnerStatus)

Describes the status of a business partner with respect to its level of activity (e.g. out of business) or legally relevant conditions (e.g. in liquidation).

profileobject(PartnerProfile)

Additional documentation can be found here.

relationsArray of objects(BusinessPartnerRelation)

List of Relations. Insert or update Business Partner Relations. Relations that are not listed in the request and start in the current business partner, are marked as INACTIVE.

In D&B storages, only not listed relations of class D&B Hierarchy and one of type [https://meta.cdq.com/Business_partner/relation/type/direct_legal_relation](Direct Legal Relation), [https://meta.cdq.com/Business_partner/relation/type/domestic_legal_ultimate_relation](Domestic Legal Ultimate Relation) or [https://meta.cdq.com/Business_partner/relation/type/global_legal_ultimate_relation](Global Legal Ultimate Relation), are marked as INACTIVE.

typesArray of objects(BusinessPartnerType)

List of Types.

addressesArray of objects(Address)

List of Addresses.

bankAccountsArray of objects(BankAccount)

List of Bank Accounts.

externalContextobject(ExternalContext)

Represents additional context information that is external to the main Business Partner data.

Response
application/json
{
  "id": "63e635235c06b7396330fe40",
  "createdAt": "2020-08-31T16:47+00:00",
  "modifiedAt": "2020-08-31T16:47+00:00",
  "externalId": "The ID managed in the customer's SAP systems.",
  "dataSource": "\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\"",
  "disclosed": "false",
  "updateMonitoring": "true",
  "updateCommercialMonitoring": [
    { … }
  ],
  "metadata": {
    "lastUpdatedAt": "2020-08-31T16:47+00:00",
    "lastSyncAt": "2020-02-11T00:00:00Z",
    "sharingStatus": { … },
    "identityLinks": [ … ],
    "logResultStatuses": [ … ],
    "decisionLogResult": { … }
  },
  "record": "{\"name\": \"BUSINESSPARTNER_NAME\", ...}",
  "additionalInformation": [
    { … }
  ],
  "names": [
    { … }
  ],
  "legalForm": {
    "name": "Aktiengesellschaft",
    "url": "https://meta.cdq.com/Business_partner/legal_form",
    "technicalKey": "DE_9866",
    "language": { … },
    "mainAbbreviation": "AG",
    "categories": [ … ]
  },
  "identifiers": [
    { … }
  ],
  "categories": [
    { … }
  ],
  "status": {
    "type": { … },
    "officialDenotation": "Good Standing",
    "validFrom": "2022-02-26",
    "validUntil": "2022-02-26"
  },
  "profile": {
    "minorityIndicator": { … },
    "classifications": [ … ],
    "phoneNumbers": [ … ],
    "websites": [ … ],
    "contactEmails": [ … ],
    "tags": [ … ],
    "vatPayerStatus": { … },
    "hcpProfile": { … }
  },
  "relations": [
    { … }
  ],
  "types": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "bankAccounts": [
    { … }
  ],
  "externalContext": {
    "identifiers": [ … ]
  }
}

List Business Partners

Request

Read a page of business partners from the storage.

Security
basicAuth
Query
startAfterstring

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
limitinteger(int32)>= 1

Number of items to be returned on the page.

Default 500
Example: limit=100
countryCodestring(CountryShortName)

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

Example: countryCode=CH
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
curl -i -X GET \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-exchange-api/api-v5/v4/cdqpool/businesspartners \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3'

Responses

OK

Bodyapplication/json
startAfterstring(StartAfter)

The ID which is used to read the page.

Example: "5712566172571652"
limitinteger(Limit)

Number of items per page.

Example: "100"
totalinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
valuesArray of objects(BusinessPartner)

List of Business Partners.

nextStartAfterstring

Available only when you used USE_NEXT_START_AFTER feature. Provides a value to be used as a startAfter in next page request.

Example: "5712566172571652"
Response
application/json
{
  "startAfter": "5712566172571652",
  "limit": "100",
  "total": "67",
  "values": [
    { … }
  ],
  "nextStartAfter": "5712566172571652"
}

Upsert Business Partners

Request

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.

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 in two places:

  • field externalId of a Business Partner,
  • property in record field together with the Business Partner attribute mapping rule defined in Data Mapper Definition.

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.

Security
basicAuth
Headers
X-Credential-Usernamestringrequired

Username that is passed as header parameter with the name X-Credential-Username. The header can take form of:

  • username (e.g. "lukaszmichta")
  • user id (e.g. "87b1bdb1-ba87-4522-b363-c5a0e6e917b3")
Example: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3
Bodyapplication/jsonrequired

Parameters for Business Partners Upsert.

dataSourcestring(BusinessPartnerDataSource)

Name or ID of a data source. Reflects the associated external system where the record originates from.

Example: "\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\""
dataMapperDefinitionIdstring(DataMapperDefinitionId)

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

Example: "6440dba32b30176c5917b1b7"
dataTransformationDefinitionIdstring(DataTransformationDefinitionId)

Unique identifier for a data transformation definition.

Example: "SAP.ODM"
businessPartnersArray of objects(BusinessPartner)[ 1 .. 1000 ] itemsrequired

List of Business Partners.

businessPartners[].​idstring(BusinessPartnerId)

A CDQ ID identifies a business partner uniquely in the context of the Corporate Data League.

Example: "63e635235c06b7396330fe40"
businessPartners[].​createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
businessPartners[].​modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2020-08-31T16:47+00:00"
businessPartners[].​externalIdstring(BusinessPartnerExternalId)

Arbitrary identifier type to mark customer IDs that are "external" from CDQ's perspective. This is the identifier a customer provides to identify its records.

Example: "The ID managed in the customer's SAP systems."
businessPartners[].​dataSourcestring(BusinessPartnerDataSource)

Name or ID of a data source. Reflects the associated external system where the record originates from.

Example: "\"CUSTOM_DATA_SOURCE\" or \"648824a691d8d2503d65103e\""
businessPartners[].​disclosedboolean(BusinessPartnerDisclosed)

A flag to indicate whether the Business Partner should participate in the sharing or not. If 'true' this Business Partner might be used to create a new entry or update an existing entry in the community pool. Otherwise, it will not be considered for the sharing process. For more details, you can read about Sharing Scopes.

Example: "false"
businessPartners[].​updateMonitoringboolean(BusinessPartnerUpdateMonitoring)

A flag to indicate whether the Business Partner should receive updates from non-commercial Reference Data Sources or not. If 'true' this Business Partner will receive updates since the change from 'false'. If 'false' this Business Partner will not receive any new updates since the change. If not provided, the previous value will not be changed. By default, Update Monitoring is activated.

Example: "true"
businessPartners[].​updateCommercialMonitoringArray of objects(BusinessPartnerUpdateCommercialMonitoring)

Enabling update commercial monitoring has 2 possibilities:

  • via Data Mapper Definition: include mapping of updateCommercialMonitoring in the Data Mapper Definition
  • via direct Business Partner model upload: fill complete Business Partner model and updateCommercialMonitoring. Null/undefined updateCommercialMonitoring results in protection of this setup from the previous upsert. Empty or filled updateCommercialMonitoring results in data transition that may link or unlink to / from respective commercial Reference Data Source

Note: follow the approach that is currently used in your storage integration.

businessPartners[].​metadataobject(BusinessPartnerMetadata)

Information about results of Business Partner processing.

businessPartners[].​recordstring(BusinessPartnerRecord)

Stringified JSON of an individual Business Partner record. Characters: backslash \ and double quote " must be escaped (respectively: \\\\ and \"). Fields containing . are unallowed. Maximum size: 15MB.

Example: "{\"name\": \"BUSINESSPARTNER_NAME\", ...}"
businessPartners[].​additionalInformationArray of objects(AdditionalInformation)

List of additional information.

businessPartners[].​namesArray of objects(Name)

List of names.

businessPartners[].​legalFormobject(LegalForm)

The legal form of a business partner/type/legal entity is the form it takes in the eyes of the law governing it. The legal form of a company is the general type it may legally use to identify itself according to the local, regional, national, or international law governing it. This is normally reflected in the ending abbreviation after the company's name (e.g. AG, Inc., LLC, S.A.).

businessPartners[].​identifiersArray of objects(Identifier)

List of Identifiers.

businessPartners[].​categoriesArray of objects(BusinessPartnerCategory)

List of Categories.

businessPartners[].​statusobject(BusinessPartnerStatus)

Describes the status of a business partner with respect to its level of activity (e.g. out of business) or legally relevant conditions (e.g. in liquidation).

businessPartners[].​profileobject(PartnerProfile)

Additional documentation can be found here.

businessPartners[].​relationsArray of objects(BusinessPartnerRelation)

List of Relations. Insert or update Business Partner Relations. Relations that are not listed in the request and start in the current business partner, are marked as INACTIVE.

In D&B storages, only not listed relations of class D&B Hierarchy and one of type [https://meta.cdq.com/Business_partner/relation/type/direct_legal_relation](Direct Legal Relation), [https://meta.cdq.com/Business_partner/relation/type/domestic_legal_ultimate_relation](Domestic Legal Ultimate Relation) or [https://meta.cdq.com/Business_partner/relation/type/global_legal_ultimate_relation](Global Legal Ultimate Relation), are marked as INACTIVE.

businessPartners[].​typesArray of objects(BusinessPartnerType)

List of Types.

businessPartners[].​addressesArray of objects(Address)

List of Addresses.

businessPartners[].​bankAccountsArray of objects(BankAccount)

List of Bank Accounts.

businessPartners[].​externalContextobject(ExternalContext)

Represents additional context information that is external to the main Business Partner data.

featuresOnArray of strings(UpsertFeatureParam)

Features to be activated during the upsert.

Items Enum ValueDescription
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.

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.

Example: ["UPSERT_BY_EXTERNAL_ID"]
featuresOffArray of strings(UpsertFeatureParam)

Features to be deactivated during the upsert.

Items Enum ValueDescription
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.

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.

Example: ["UPSERT_BY_EXTERNAL_ID"]
curl -i -X PUT \
  -u <username>:<password> \
  https://idp.cdq.com/_mock/apis/data-exchange-api/api-v5/v4/cdqpool/businesspartners \
  -H 'Content-Type: application/json' \
  -H 'X-Credential-Username: 87b1bdb1-ba87-4522-b363-c5a0e6e917b3' \
  -d '{
    "dataSource": "YOUR_DATASOURCE_ID",
    "featuresOn": [
      "UPSERT_BY_EXTERNAL_ID"
    ],
    "businessPartners": [
      {
        "externalId": "YOUR_EXTERNAL_ID",
        "record": "{\"Customer number:\"YOUR_EXTERNAL_ID\", \"Name\":\"COMPANY_NAME\", \"Country\":\"COUNTRY_CODE\", \"City\":\"CITY\", \"Street\":\"STREET\", \"Postal code\":\"POSTAL_CODE\"}"
      }
    ]
  }'

Responses

OK

Bodyapplication/json
numberOfAcceptedinteger

When asynchronous processing activated (ENABLE_ASYNC or LAB_USE_QUEUES), then represents number of Business Partners to be processed asynchronously. When synchronous processing activated, then provides number of Business Partners processed.

Example: "10"
numberOfInsertsinteger

Number of inserted Business Partners.

Example: "10"
numberOfUpdatesinteger

Number of updated Business Partners.

Example: "10"
numberOfFailedinteger

Number of failed inserts.

Example: "10"
failuresArray of objects(UpsertFailureLog)

List of failures.

featuresOnArray of strings(UpsertFeature)

List of features that cna be activated during the upsert.

Example: ["UPSERT_BY_EXTERNAL_ID"]
Response
application/json
{
  "numberOfAccepted": "10",
  "numberOfInserts": "10",
  "numberOfUpdates": "10",
  "numberOfFailed": "10",
  "failures": [
    { … }
  ],
  "featuresOn": [
    "UPSERT_BY_EXTERNAL_ID"
  ]
}

Data Import

Provides functionalities for uploading external data and enabling users to enhance and update their Business Partner records with new information.

Operations

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.

Operations

Data Monitors

Provides functionalities for creating, retrieving, updating and deleting data monitors.

Operations

Data Transformation

Provides functionalities for converting raw data into structured formats.

Operations

DNB Storages

Provides functionalities for creating, retrieving, updating and deleting DNB storage, as well as managing associated data sources and data monitors.

Operations

Files

Provides functionalities for uploading, downloading and deleting files.

Operations

Subscriptions

Provides functionalities for managing subscriptions.

Operations

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.

Operations

Relations

Manages relationships between Business Partners.

Operations

Update Classification

Operations

Event Stores

Operations

Business Partner Storages (None Public)

Operations

Restart Monitor Job

Operations

Cache

Operations

Configuration

Operations

Event Store

Operations

CDQ Community Pool

Operations