Skip to content

Data Exchange API (5)

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

Download OpenAPI description
api-v5.json
api-v5.yaml
Languages
Servers
Production

https://api.cdq.com/data-exchange/rest/

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.

Operations

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

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

Create Data Mapper Definition

Request

Create a Data Mapper Definition which is used to map data (i.e. in the format from the database) to the CDQ data model.

Data mapper definition consists of:

  • inputMapping - definition how to map businessPartner.record to CDQ data model
  • outputMapping - definition how to map CDQ data model to the target model

Business partner can be mapped via businessPartnerAttributeMappings. The following values of attribute mapping rules:

  • as targetAttributes for inputMapping
  • as sourceAttributes for outputMapping (please remember they are case sensitive)

can be mapped to Business Partner attributes:

  • businessPartner.dataSource
  • businessPartner.externalId
  • businessPartner.disclosed - special attribute. When defined in a mapping, takes over the decision for disclosing records in data source this Data Mapper Definition is assigned to. When source attribute is mapped from record, the mapping takes the value. If the attribute is missing, disclosed is set to false.
  • businessPartner.names[0-10].value
  • businessPartner.names[0-10].shortName
  • businessPartner.names[0-10].language
  • businessPartner.names[0-10].type
  • businessPartner.names
  • businessPartner.legalForm.name
  • businessPartner.legalForm.categories[0-4].technicalKey
  • businessPartner.categories
  • businessPartner.identifiers[0-49].value
  • businessPartner.identifiers[0-49].type
  • businessPartner.identifiers[0-49].issuingBody.name
  • businessPartner.identifiers[0-49].issuingBody - mapped to issuingBody.technicalKey
  • businessPartner.identifiers[0-49].status
  • businessPartner.identifiers
  • businessPartner.externalContext.identifiers[0-49].value
  • businessPartner.externalContext.identifiers[0-49].type
  • businessPartner.externalContext.identifiers

The index of typed concepts: names and identifiers, is not a final position of concept in the CDQ data model - this is a grouping indicator for a set of concept properties.

In Names mapping, in case none of names is typed LOCAL and exists any name with empty type or not filled type.technicalKey, it becomes name of type LOCAL.

Addresses can be mapped via addressesAttributeMappings. Address receives id property coming from an index of the collection of AttributeMappingRules. The following values of attribute mapping rules

  • as targetAttributes for inputMapping
  • as sourceAttributes for outputMapping

can be mapped to address attributes:

  • address.externalId
  • address.version.language
  • address.version.characterSet
  • address.careOf.value
  • address.identifyingName.value
  • address.country.value
  • address.country.shortName
  • address.administrativeAreas
  • address.administrativeAreas[0-4].value
  • address.administrativeAreas[0-4].shortName
  • address.administrativeAreas[0-4].type
  • address.postCodes
  • address.postCodes[0-4].value
  • address.postCodes[0-4].type
  • address.localities
  • address.localities[0-4].value
  • address.localities[0-4].shortName
  • address.localities[0-4].type
  • address.thoroughfares
  • address.thoroughfares[0-4].value
  • address.thoroughfares[0-4].shortName
  • address.thoroughfares[0-4].number
  • address.thoroughfares[0-4].type
  • address.premises
  • address.premises[0-4].value
  • address.premises[0-4].shortName
  • address.premises[0-4].number
  • address.premises[0-4].type
  • address.postalDeliveryPoints
  • address.postalDeliveryPoints[0-4].value
  • address.postalDeliveryPoints[0-4].shortName
  • address.postalDeliveryPoints[0-4].number
  • address.postalDeliveryPoints[0-4].type
  • address.geographicCoordinates.latitude
  • address.geographicCoordinates.longitude
  • address.contexts
  • address.contexts[0-4]
Security
apiKey
Bodyapplication/jsonrequired

Request to create a new Data Mapper Definition.

namestringrequired

Name of the Data Mapper Definition.

Example: "Custom Data Mapper Definition"
labelsArray of strings

Labels to categorize the Data Mapper Definition.

Example: ["Custom Data Mapper Label"]
shareWithOrganizationboolean

Toggle to enable that the Data Mapper Definition is shared with the whole organization.

Example: "true"
valueMappingsArray of objects(ValueMapping)

List of value mappings.

inputMappingobject(BusinessPartnerMappingRule)required

Maps a Business Partner data from raw data to CDQ data model.

inputMapping.​businessPartnerAttributeMappingsArray of objects(AttributeMappingRule)

List of Business Partner Attribute Mappings.

inputMapping.​addressesAttributeMappingsArray of objects(AttributeMappingRule)

Maps an address attribute from raw data to CDQ data model.

outputMappingobject(BusinessPartnerMappingRule)

Maps a Business Partner data from raw data to CDQ data model.

curl -i -X POST \
  https://api.cdq.com/data-exchange/rest/datamapperdefinitions \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "name": "CustomDataMapperDefinition",
    "labels": [
      "CustomDataMapperLabel"
    ],
    "shareWithOrganization": true,
    "valueMappings": [
      {
        "sourceValue": "en",
        "targetValue": "INTERNATIONAL",
        "targetAttribute": "address.version.characterSet"
      }
    ],
    "inputMapping": {
      "businessPartnerAttributeMappings": [
        {
          "sourceConstant": "LOCAL",
          "sourceAttributes": [
            "Name"
          ],
          "targetAttributes": [
            "businessPartner.names[0].value"
          ],
          "targetAttributeTypes": [
            "LOCAL"
          ],
          "countryScopes": [
            "DE"
          ],
          "selectionType": "COMMA",
          "separationType": "LENGTH",
          "isMandatoryAttribute": "true",
          "valueMapping": "INTERNATIONAL",
          "defaultValue": "GB",
          "transformations": [
            {
              "type": "UPPER_CASE",
              "parameters": [
                {}
              ]
            }
          ]
        }
      ],
      "addressesAttributeMappings": [
        [
          {
            "sourceConstant": "LOCAL",
            "sourceAttributes": [
              "Name"
            ],
            "targetAttributes": [
              "businessPartner.names[0].value"
            ],
            "targetAttributeTypes": [
              "LOCAL"
            ],
            "countryScopes": [
              "DE"
            ],
            "selectionType": "COMMA",
            "separationType": "LENGTH",
            "isMandatoryAttribute": "true",
            "valueMapping": "INTERNATIONAL",
            "defaultValue": "GB",
            "transformations": [
              {
                "type": "UPPER_CASE",
                "parameters": [
                  null
                ]
              }
            ]
          }
        ]
      ]
    },
    "outputMapping": {
      "businessPartnerAttributeMappings": [
        {
          "sourceConstant": "LOCAL",
          "sourceAttributes": [
            "Name"
          ],
          "targetAttributes": [
            "businessPartner.names[0].value"
          ],
          "targetAttributeTypes": [
            "LOCAL"
          ],
          "countryScopes": [
            "DE"
          ],
          "selectionType": "COMMA",
          "separationType": "LENGTH",
          "isMandatoryAttribute": "true",
          "valueMapping": "INTERNATIONAL",
          "defaultValue": "GB",
          "transformations": [
            {
              "type": "UPPER_CASE",
              "parameters": [
                {}
              ]
            }
          ]
        }
      ],
      "addressesAttributeMappings": [
        [
          {
            "sourceConstant": "LOCAL",
            "sourceAttributes": [
              "Name"
            ],
            "targetAttributes": [
              "businessPartner.names[0].value"
            ],
            "targetAttributeTypes": [
              "LOCAL"
            ],
            "countryScopes": [
              "DE"
            ],
            "selectionType": "COMMA",
            "separationType": "LENGTH",
            "isMandatoryAttribute": "true",
            "valueMapping": "INTERNATIONAL",
            "defaultValue": "GB",
            "transformations": [
              {
                "type": "UPPER_CASE",
                "parameters": [
                  null
                ]
              }
            ]
          }
        ]
      ]
    }
  }'

Responses

OK

Bodyapplication/json
idstring(DataMapperDefinitionId)

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

Example: "6440dba32b30176c5917b1b7"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"
createdBystring(CreatedBy)

Creator of a resource.

Example: "76248934691294444"
modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"
modifiedBystring(ModifiedBy)

User or Client UUID which modified the resource.

Example: "76248934691294444"
creatorUsernamestring

Username of the creator of the Data Mapper Definition.

Example: "john.doe"
creatorOrganizationstring

Organization of the creator of the Data Mapper Definition.

Example: "cdq"
shareWithOrganizationboolean

Toggle to enable that the Data Mapper Definition is shared with the whole organization.

Example: "true"
labelsArray of strings(StorageLabels)<= 10 itemsunique

List of labels.

Example: ["Custom Storage Name"]
namestring

Name of the Data Mapper Definition.

Example: "Custom name of Data Mapper"
valueMappingsArray of objects(ValueMapping)

List of Value Mappings.

inputMappingobject(BusinessPartnerMappingRule)

Maps a Business Partner data from raw data to CDQ data model.

outputMappingobject(BusinessPartnerMappingRule)

Maps a Business Partner data from raw data to CDQ data model.

lastUpdatedAtstringDeprecated

Deprecated, please use modifiedAt instead.

Example: "2025-08-19T06:23:16Z"
Response
application/json
{
  "id": "6440dba32b30176c5917b1b7",
  "createdAt": "2025-08-19T06:23:16Z",
  "createdBy": "76248934691294444",
  "lastUpdatedAt": "2025-08-19T06:23:16Z",
  "modifiedAt": "2025-08-19T06:23:16Z",
  "modifiedBy": "76248934691294444",
  "creatorUsername": "john.doe",
  "creatorOrganization": "cdq",
  "shareWithOrganization": "true",
  "labels": [
    "Custom Storage Name"
  ],
  "name": "Custom name of Data Mapper",
  "valueMappings": [
    { … }
  ],
  "inputMapping": {
    "businessPartnerAttributeMappings": [ … ],
    "addressesAttributeMappings": [ … ]
  },
  "outputMapping": {
    "businessPartnerAttributeMappings": [ … ],
    "addressesAttributeMappings": [ … ]
  }
}

List Data Mapper Definitions

Request

Read the Data Mapper Definition Page.

Security
apiKey
Query
labelArray of strings

Label for filtering that is passed as header parameter with the name label.

Example: label=Custom label
sharedWithOrganizationboolean

Filters only mappings which are shared with organization or not.

Example: sharedWithOrganization=true
pageinteger(int32)>= 0

Number of the page that will be retrieved.

Default 0
Example: page=10
pageSizeinteger(int32)>= 1

Number of items to be returned on the page.

Default 20
Example: pageSize=10
sortstring

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

Example: sort=-modifiedAt
curl -i -X GET \
  https://api.cdq.com/data-exchange/rest/datamapperdefinitions \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
numberOfPagesinteger(int32)(NumberOfPages)

Number of pages.

Example: "10"
pageinteger(Page)>= 0

Current page number.

Default 0
Example: "1"
pageSizeinteger(PageSize)[ 1 .. 1000 ]

Number of items per page.

Default 10
Example: "100"
totalinteger(PageTotal)

Total number of items which can be paged.

Example: "67"
valuesArray of objects(DataMapperDefinition)

List of Data Mapper Definitions.

Response
application/json
{
  "numberOfPages": "10",
  "page": "1",
  "pageSize": "100",
  "total": "67",
  "values": [
    { … }
  ]
}

Read Data Mapper Definition

Request

Read a Data Mapper Definition.

Security
apiKey
Path
idstring(DataMapperDefinitionId)required

Unique ID of the Data Mapper Definition.

Example: 6440dba32b30176c5917b1b7
curl -i -X GET \
  https://api.cdq.com/data-exchange/rest/datamapperdefinitions/6440dba32b30176c5917b1b7 \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring(DataMapperDefinitionId)

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

Example: "6440dba32b30176c5917b1b7"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"
createdBystring(CreatedBy)

Creator of a resource.

Example: "76248934691294444"
modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"
modifiedBystring(ModifiedBy)

User or Client UUID which modified the resource.

Example: "76248934691294444"
creatorUsernamestring

Username of the creator of the Data Mapper Definition.

Example: "john.doe"
creatorOrganizationstring

Organization of the creator of the Data Mapper Definition.

Example: "cdq"
shareWithOrganizationboolean

Toggle to enable that the Data Mapper Definition is shared with the whole organization.

Example: "true"
labelsArray of strings(StorageLabels)<= 10 itemsunique

List of labels.

Example: ["Custom Storage Name"]
namestring

Name of the Data Mapper Definition.

Example: "Custom name of Data Mapper"
valueMappingsArray of objects(ValueMapping)

List of Value Mappings.

inputMappingobject(BusinessPartnerMappingRule)

Maps a Business Partner data from raw data to CDQ data model.

outputMappingobject(BusinessPartnerMappingRule)

Maps a Business Partner data from raw data to CDQ data model.

lastUpdatedAtstringDeprecated

Deprecated, please use modifiedAt instead.

Example: "2025-08-19T06:23:16Z"
Response
application/json
{
  "id": "6440dba32b30176c5917b1b7",
  "createdAt": "2025-08-19T06:23:16Z",
  "createdBy": "76248934691294444",
  "lastUpdatedAt": "2025-08-19T06:23:16Z",
  "modifiedAt": "2025-08-19T06:23:16Z",
  "modifiedBy": "76248934691294444",
  "creatorUsername": "john.doe",
  "creatorOrganization": "cdq",
  "shareWithOrganization": "true",
  "labels": [
    "Custom Storage Name"
  ],
  "name": "Custom name of Data Mapper",
  "valueMappings": [
    { … }
  ],
  "inputMapping": {
    "businessPartnerAttributeMappings": [ … ],
    "addressesAttributeMappings": [ … ]
  },
  "outputMapping": {
    "businessPartnerAttributeMappings": [ … ],
    "addressesAttributeMappings": [ … ]
  }
}

Update Data Mapper Definition

Request

Update a Data Mapper Definition. For more information what are the allowed Data Mapper values, go to creation endpoint description.

Security
apiKey
Path
idstring(DataMapperDefinitionId)required

Unique ID of the Data Mapper Definition.

Example: 6440dba32b30176c5917b1b7
Bodyapplication/jsonrequired

Request to create a new Data Mapper Definition.

namestringrequired

Name of the Data Mapper Definition.

Example: "Custom Data Mapper Definition"
labelsArray of strings

Labels to categorize the Data Mapper Definition.

Example: ["Custom Data Mapper Label"]
shareWithOrganizationboolean

Toggle to enable that the Data Mapper Definition is shared with the whole organization.

Example: "true"
valueMappingsArray of objects(ValueMapping)

List of value mappings.

inputMappingobject(BusinessPartnerMappingRule)required

Maps a Business Partner data from raw data to CDQ data model.

inputMapping.​businessPartnerAttributeMappingsArray of objects(AttributeMappingRule)

List of Business Partner Attribute Mappings.

inputMapping.​addressesAttributeMappingsArray of objects(AttributeMappingRule)

Maps an address attribute from raw data to CDQ data model.

outputMappingobject(BusinessPartnerMappingRule)

Maps a Business Partner data from raw data to CDQ data model.

curl -i -X PUT \
  https://api.cdq.com/data-exchange/rest/datamapperdefinitions/6440dba32b30176c5917b1b7 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "name": "CustomDataMapperDefinition",
    "labels": [
      "CustomDataMapperLabel"
    ],
    "shareWithOrganization": true,
    "valueMappings": [
      {
        "sourceValue": "en",
        "targetValue": "INTERNATIONAL",
        "targetAttribute": "address.version.characterSet"
      }
    ],
    "inputMapping": {
      "businessPartnerAttributeMappings": [
        {
          "sourceConstant": "LOCAL",
          "sourceAttributes": [
            "Name"
          ],
          "targetAttributes": [
            "businessPartner.names[0].value"
          ],
          "targetAttributeTypes": [
            "LOCAL"
          ],
          "countryScopes": [
            "DE"
          ],
          "selectionType": "COMMA",
          "separationType": "LENGTH",
          "isMandatoryAttribute": "true",
          "valueMapping": "INTERNATIONAL",
          "defaultValue": "GB",
          "transformations": [
            {
              "type": "UPPER_CASE",
              "parameters": [
                {}
              ]
            }
          ]
        }
      ],
      "addressesAttributeMappings": [
        [
          {
            "sourceConstant": "LOCAL",
            "sourceAttributes": [
              "Name"
            ],
            "targetAttributes": [
              "businessPartner.names[0].value"
            ],
            "targetAttributeTypes": [
              "LOCAL"
            ],
            "countryScopes": [
              "DE"
            ],
            "selectionType": "COMMA",
            "separationType": "LENGTH",
            "isMandatoryAttribute": "true",
            "valueMapping": "INTERNATIONAL",
            "defaultValue": "GB",
            "transformations": [
              {
                "type": "UPPER_CASE",
                "parameters": [
                  null
                ]
              }
            ]
          }
        ]
      ]
    },
    "outputMapping": {
      "businessPartnerAttributeMappings": [
        {
          "sourceConstant": "LOCAL",
          "sourceAttributes": [
            "Name"
          ],
          "targetAttributes": [
            "businessPartner.names[0].value"
          ],
          "targetAttributeTypes": [
            "LOCAL"
          ],
          "countryScopes": [
            "DE"
          ],
          "selectionType": "COMMA",
          "separationType": "LENGTH",
          "isMandatoryAttribute": "true",
          "valueMapping": "INTERNATIONAL",
          "defaultValue": "GB",
          "transformations": [
            {
              "type": "UPPER_CASE",
              "parameters": [
                {}
              ]
            }
          ]
        }
      ],
      "addressesAttributeMappings": [
        [
          {
            "sourceConstant": "LOCAL",
            "sourceAttributes": [
              "Name"
            ],
            "targetAttributes": [
              "businessPartner.names[0].value"
            ],
            "targetAttributeTypes": [
              "LOCAL"
            ],
            "countryScopes": [
              "DE"
            ],
            "selectionType": "COMMA",
            "separationType": "LENGTH",
            "isMandatoryAttribute": "true",
            "valueMapping": "INTERNATIONAL",
            "defaultValue": "GB",
            "transformations": [
              {
                "type": "UPPER_CASE",
                "parameters": [
                  null
                ]
              }
            ]
          }
        ]
      ]
    }
  }'

Responses

OK

Bodyapplication/json
idstring(DataMapperDefinitionId)

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

Example: "6440dba32b30176c5917b1b7"
createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"
createdBystring(CreatedBy)

Creator of a resource.

Example: "76248934691294444"
modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"
modifiedBystring(ModifiedBy)

User or Client UUID which modified the resource.

Example: "76248934691294444"
creatorUsernamestring

Username of the creator of the Data Mapper Definition.

Example: "john.doe"
creatorOrganizationstring

Organization of the creator of the Data Mapper Definition.

Example: "cdq"
shareWithOrganizationboolean

Toggle to enable that the Data Mapper Definition is shared with the whole organization.

Example: "true"
labelsArray of strings(StorageLabels)<= 10 itemsunique

List of labels.

Example: ["Custom Storage Name"]
namestring

Name of the Data Mapper Definition.

Example: "Custom name of Data Mapper"
valueMappingsArray of objects(ValueMapping)

List of Value Mappings.

inputMappingobject(BusinessPartnerMappingRule)

Maps a Business Partner data from raw data to CDQ data model.

outputMappingobject(BusinessPartnerMappingRule)

Maps a Business Partner data from raw data to CDQ data model.

lastUpdatedAtstringDeprecated

Deprecated, please use modifiedAt instead.

Example: "2025-08-19T06:23:16Z"
Response
application/json
{
  "id": "6440dba32b30176c5917b1b7",
  "createdAt": "2025-08-19T06:23:16Z",
  "createdBy": "76248934691294444",
  "lastUpdatedAt": "2025-08-19T06:23:16Z",
  "modifiedAt": "2025-08-19T06:23:16Z",
  "modifiedBy": "76248934691294444",
  "creatorUsername": "john.doe",
  "creatorOrganization": "cdq",
  "shareWithOrganization": "true",
  "labels": [
    "Custom Storage Name"
  ],
  "name": "Custom name of Data Mapper",
  "valueMappings": [
    { … }
  ],
  "inputMapping": {
    "businessPartnerAttributeMappings": [ … ],
    "addressesAttributeMappings": [ … ]
  },
  "outputMapping": {
    "businessPartnerAttributeMappings": [ … ],
    "addressesAttributeMappings": [ … ]
  }
}

Delete Data Mapper Definition

Request

Delete chosen Data Mapper Definition.

Security
apiKey
Path
idstring(DataMapperDefinitionId)required

Unique ID of the Data Mapper Definition.

Example: 6440dba32b30176c5917b1b7
curl -i -X DELETE \
  https://api.cdq.com/data-exchange/rest/datamapperdefinitions/6440dba32b30176c5917b1b7 \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

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

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

Subscriptions

Operations