Data Import

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

Start Import Job

Request

To start importing a file into a storage, use the following request.

POST https://api.corporate-data-league.ch/data-exchange/rest/jobs/importjobs
  ?file=@{YOUR FILE}
  ?storageId={YOUR STORAGE ID}
  ?dataSource={YOUR DATASOURCE ID}

Fields (cells) in a file, that contain a special character (comma, semicolon, CR, LF, or double quote), must be "escaped" by enclosing them in double quotes. Header names can not contain any dot.

In order to successfully perform file upload use file upload for files up to 10MB or Upload via Upload Request approach for files larger than 10MB. file and url are not allowed to be present together.

Use one of the below instructions for your case:

File size < 10MB : File Upload
File size > 10MB : Request Upload

Including this sample CSV file in the default configuration.

Customer Number;City
123;St. Gallen

Supported columns (matched by ignoring letter case) with their mappings are the following:

Column Name	Target Path in the latest Business Partner Model	Wiki Page of Attribute in CDQ Data Model
CUSTOMER NUMBER	$.externalId	Business Partner External ID
VENDOR NUMBER	$.externalId when `CUSTOMER NUMBER` is not available	Business Partner External ID
NAME	$.names[0].value, $.names[0].type.technicalKey = LOCAL	Business Partner Name Value
TAX NUMBER 1	$.identifiers[identifierId].value in identifierId of `TAX NUMBER 1 TYPE` if exists, otherwise, new identifier of STCD1 type mapping, applied for `COUNTRY`	Identifier Value
TAX NUMBER 1 TYPE	$.identifiers[identifierId].type	Identifier Type
TAX NUMBER 2	$.identifiers[identifierId].value in identifierId of `TAX NUMBER 2 TYPE` if exists, otherwise, new identifier of STCD2 type mapping, applied for `COUNTRY`	Identifier Value
TAX NUMBER 2 TYPE	$.identifiers[identifierId].type	Identifier Type
TAX NUMBER 3	$.identifiers[identifierId].value in identifierId of `TAX NUMBER 3 TYPE` if exists, otherwise, new identifier of STCD3 type mapping, applied for `COUNTRY`	Identifier Value
TAX NUMBER 3 TYPE	$.identifiers[identifierId].type	Identifier Type
TAX NUMBER 4	$.identifiers[identifierId].value in identifierId of `TAX NUMBER 4 TYPE` if exists, otherwise, new identifier of STCD4 type mapping, applied for `COUNTRY`	Identifier Value
TAX NUMBER 4 TYPE	$.identifiers[identifierId].type	Identifier Type
TAX NUMBER 5	$.identifiers[identifierId].value in identifierId of `TAX NUMBER 5 TYPE` if exists, otherwise, new identifier of STCD5 type mapping, applied for `COUNTRY`	Identifier Value
TAX NUMBER 5 TYPE	$.identifiers[identifierId].type	Identifier Type
VAT NUMBER	$.identifiers[identifierId].value in identifierId of `VAT NUMBER TYPE` if exists, otherwise, new identifier of STCEG type mapping, applied for `COUNTRY`	Identifier Value
VAT NUMBER TYPE	$.identifiers[identifierId].type	Identifier Type
COUNTRY	address.country.(value, shortName) in $.addresses[0] (+ in $.addresses[1] when `PO BOX` exists for non-France)	Country
REGION	address.administrativeAreas[0].value in $.addresses[0] (+ in $.addresses[1] when `PO BOX` exists for non-France)	Administrative Area Value
POSTAL CODE	address.postCodes[0].value in $.addresses[0] (+ in $.addresses[1] when `PO BOX` exists for non-France)	Post Code Value
CITY	address.localities[0].value in $.addresses[0] (+ in $.addresses[1] when `PO BOX` exists for non-France)	Locality Value
STREET	address.thoroughfares[0].value	Thoroughfare Value
HOUSE NUMBER	address.thoroughfares[0].number	Thoroughfare Number
PO BOX	address.postalDeliveryPoints[0].value, address.postalDeliveryPoints[0].type.technicalKey = POST_OFFICE_BOX in $.addresses[0] in France, in $.addresses[1] for non-France	https://meta.cdq.com/Business_partner/external_id

Alternatively, CUSTOM_DATA_MAPPER feature can be used to enable record transformation based on the Data Mapper Definition provided either via a dataMapperDefinitionId field or assigned to provided data source.

Input file could contain customized columns naming effectively mapped to the Business Partner model via data mapper, shown in this sample CSV.

MyId;Country;City;Name
123;CH;St. Gallen;
124;CH;;Quote "Example"
"125";"CH";"";"""Quote """"Example""""  """

Input file for CUSTOM_DATA_MAPPER feature can also contain only one Record column with a stringified JSON representation of a record. Based on the Data Mapper Definition, data is transformed to the Business Partner model. In case UPSERT_BY_EXTERNAL_ID feature is used, external ID value needs to be included:

in a column which name is provided via a extenalIdColumn request property
in the JSON representation in the attribute mapped to externalId via data mapper

Below is the sample CSV file for Record-based configuration containing external ID column named MyId.

MyId,Record
123,"{""MyId"": ""123"", ""Country"": ""CH"", ""City"": ""St. Gallen""}"
124,"{""MyId"": ""124"", ""Country"": ""CH"", ""Name"": ""Quote \""Example\""""}"
125,"{""MyId"": ""125"", ""Country"": ""CH"", ""Name"": ""\""Quote \""\""Example\""\""  \""""}"

The maximum number of columns is 512

The response is shown below. Use the returned id to poll the import job status.

{
    "id" : "{YOUR IMPORT JOB ID}"
    ...
}

These imports, in default import samples, lead to the following Business Partners in the storage. The imported rows are represented as stringified JSONs.

{
   "id" : "{AUTO GENERATED}",
   "externalId" : "123",
   "dataSource": "{YOUR DATASOURCE ID}",
   "record" : "{ \"MyId\" : \"123\", \"Country\" : \"CH\", \"City\" : \"St. Gallen\" }",
   "addresses": [{
      "country": {
         "shortName": "CH"
      },
      "localities": [{
         "value": "St. Gallen"
      }]
   }],
   ...
},
{
   "id" : "{AUTO GENERATED}",
   "externalId" : "124",
   "dataSource": "{YOUR DATASOURCE ID}",
   "record" : "{ \"MyId\" : \"124\", \"Country\" : \"CH\", \"Name\" : \"Quote \\\"Example\\\"\" }",
   "names": [{
      "value": "Quote \"Example\""
      ...
   }],
   "addresses": [{
      "country": {
         "shortName": "CH"
      }
   }],
   ...
},
{
   "id" : "{AUTO GENERATED}",
   "externalId" : "125",
   "dataSource": "{YOUR DATASOURCE ID}",
   "record" : "{ \"MyId\" : \"125\", \"Country\" : \"CH\", \"Name\" : \"\\\"Quote \\\"\\\"Example\\\"\\\"  \\\"\" }",
   "names": [{
      "value": "\"Quote \"\"Example\"\"  \""
      ...
   }],
   "addresses": [{
      "country": {
         "shortName": "CH"
      }
   }],
   ...
}

Input file which first 100 data lines except header are corrupted is canceled without further processing.

Importing data to Data Mirror requires using "UPSERT_BY_EXTERNAL_ID" feature. Otherwise, Bad Request is reported.

Security

apiKey

Bodymultipart/form-data

filestring(binary)

XLSX or CSV file to be uploaded (SOAP currently only supports CSV). Supports up to 10MB of file size. For the file size greater than 10MB use Upload via Upload Request approach.

Example: "CH-import.csv"

urlstring

Url to file which will be used to import data from. Recommended. The file can be uploaded via File Upload passing through url from the result object.

Example: "customer-uploads/CH-import.csv"

storageIdstringrequired

Target storage ID for this import.

Example: "72d6900fce6b326088f5d9d91049e3e6"

dataSourcestring(BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "648824a691d8d2503d65103e"

externalIdColumnstring

The name of the column which will be mapped to external ID. This is required if feature UPSERT_BY_EXTERNAL_ID is activated.

Example: "BP_EXTERNAL_ID"

dataMapperDefinitionIdstring

The ID of data mapper to be used to transform the data before importing it. This or a data source is required if feature CUSTOM_DATA_MAPPER is activated. Disabled when CUSTOM_DATA_MAPPER feature is not provided in a request.

Example: "6400955811c68a034bcef311"

featuresOnArray of strings

List of features to be activated.

Items Enum Value	Description
ACCEPT_EMPTY_VALUES	Allows to import empty values to record in Business Partner.
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. If this feature is selected, `dataSource` and `externalIdColumn` are mandatory. When selected, id must not be provided in a Business Partner.
CUSTOM_DATA_MAPPER	Applies data transformation using data mapper identified by `dataMapperDefinitionId` field or fetched from the data source identified by `dataSource` field.
FULL_UPDATE	Forces the job to delete existing records which are not included in the import file. Records to be updated or to be deleted are identified by external IDs, i.e. not by the internal database IDs. To confirm this understanding, UPSERT_BY_EXTERNAL_ID feature must be activated in addition. When a FULL_UPDATE import job is completed, new records from the import file are created, existing ones are updated by keeping their internal database IDs and their external IDs, and records which are not provided by the file are deleted. If this feature is selected, dataSource and `UPSERT_BY_EXTERNAL_ID` feature are mandatory. Whenever import errors occur then this action is not executed.

Example: ["UPSERT_BY_EXTERNAL_ID"]

curl -i -X POST \
  https://api.cdq.com/data-exchange/rest/jobs/importjobs \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -F file=CH-import.csv \
  -F url=customer-uploads/CH-import.csv \
  -F storageId=72d6900fce6b326088f5d9d91049e3e6 \
  -F dataSource=648824a691d8d2503d65103e \
  -F externalIdColumn=BP_EXTERNAL_ID \
  -F dataMapperDefinitionId=6400955811c68a034bcef311 \
  -F featuresOn=UPSERT_BY_EXTERNAL_ID

Responses

OK

Bodyapplication/json

idstring(JobId)

Unique identifier of a job.

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

namestring(JobName)

Name of a Job.

Example: "Process vendor data."

descriptionstring(JobDescription)

Detailed description of a Job.

Example: "I started this job to improve quality of our data."

createdBystring(CreatedBy)

Creator of a resource.

Example: "76248934691294444"

createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"

modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"

progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"

statusstring(JobStatus)

Job execution status.

Enum Value	Description
ARCHIVED	Job has been archived.
UNKNOWN	Job becomes in unknown status.
CREATED	Job has been created.
PERSISTED	Job metadata has been persisted.
SCHEDULED	Job has been scheduled for execution.
WAITING	Job is waiting for being scheduled.
COULDNT_START	Job could not be started.
RUNNING	Job is being executed.
FINISHED	Job has finished.
DIED	Job was scheduled and started running but died unexpectedly.

Example: "RUNNING"

statusMessagestring(JobStatusMessage)

Additional information to explain the status.

Example: "The job failed because storage is empty."

storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"

dataSourcestring(BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "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"

externalIdColumnstring

The name of the column which will be mapped to external ID. This is required if feature UPSERT_BY_EXTERNAL_ID is activated.

Example: "BP_EXTERNAL_ID"

featureOnArray of strings

List of features which are activated for the Import Job.

Example: ["UPSERT_BY_EXTERNAL_ID"]

resultobject(ImportJobResult)

The result of the Import Job.

domainstring(Domain)Deprecated

Domain of a Business Partner Storage.

Example: "BusinessPartner"

Response

application/json

{
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "name": "Process vendor data.",
  "description": "I started this job to improve quality of our data.",
  "domain": "BusinessPartner",
  "createdBy": "76248934691294444",
  "createdAt": "2025-08-19T06:23:16Z",
  "modifiedAt": "2025-08-19T06:23:16Z",
  "progress": "77",
  "status": "RUNNING",
  "statusMessage": "The job failed because storage is empty.",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "dataSource": "648824a691d8d2503d65103e",
  "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
  "dataTransformationDefinitionId": "SAP.ODM",
  "externalIdColumn": "BP_EXTERNAL_ID",
  "featureOn": [
    "UPSERT_BY_EXTERNAL_ID"
  ],
  "result": {
    "statistics": { … }
  }
}

Poll Import Job

Request

Allows polling the status of an Import Job.

Security

apiKey

Path

jobIdstring(JobId)required

Unique identifier of a Job.

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

Query

skippedStartAfterstring

Next page of items will be retrieved. When skippedNextStartAfter provided in the response, should be used.

Example: skippedStartAfter=5712566172571652

curl -i -X GET \
  https://api.cdq.com/data-exchange/rest/jobs/importjobs/35f23c03-1c22-45fe-9484-3ffe769325de \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json

idstring(JobId)

Unique identifier of a job.

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

namestring(JobName)

Name of a Job.

Example: "Process vendor data."

descriptionstring(JobDescription)

Detailed description of a Job.

Example: "I started this job to improve quality of our data."

createdBystring(CreatedBy)

Creator of a resource.

Example: "76248934691294444"

createdAtstring(CreatedAt)

Date of creation (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"

modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example: "2025-08-19T06:23:16Z"

progressinteger(JobProgress)[ 0 .. 100 ]

Progress (%) of the job.

Example: "77"

statusstring(JobStatus)

Job execution status.

Enum Value	Description
ARCHIVED	Job has been archived.
UNKNOWN	Job becomes in unknown status.
CREATED	Job has been created.
PERSISTED	Job metadata has been persisted.
SCHEDULED	Job has been scheduled for execution.
WAITING	Job is waiting for being scheduled.
COULDNT_START	Job could not be started.
RUNNING	Job is being executed.
FINISHED	Job has finished.
DIED	Job was scheduled and started running but died unexpectedly.

Example: "RUNNING"

statusMessagestring(JobStatusMessage)

Additional information to explain the status.

Example: "The job failed because storage is empty."

storageIdstring(BusinessPartnerStorageId)

Unique identifier of the Storage.

Example: "72d6900fce6b326088f5d9d91049e3e6"

dataSourcestring(BusinessPartnerStorageDataSourceId)

Unique identifier for a Data Source of the Storage.

Example: "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"

externalIdColumnstring

The name of the column which will be mapped to external ID. This is required if feature UPSERT_BY_EXTERNAL_ID is activated.

Example: "BP_EXTERNAL_ID"

featureOnArray of strings

List of features which are activated for the Import Job.

Example: ["UPSERT_BY_EXTERNAL_ID"]

resultobject(ImportJobResult)

The result of the Import Job.

domainstring(Domain)Deprecated

Domain of a Business Partner Storage.

Example: "BusinessPartner"

Response

application/json

{
  "id": "35f23c03-1c22-45fe-9484-3ffe769325de",
  "name": "Process vendor data.",
  "description": "I started this job to improve quality of our data.",
  "domain": "BusinessPartner",
  "createdBy": "76248934691294444",
  "createdAt": "2025-08-19T06:23:16Z",
  "modifiedAt": "2025-08-19T06:23:16Z",
  "progress": "77",
  "status": "RUNNING",
  "statusMessage": "The job failed because storage is empty.",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "dataSource": "648824a691d8d2503d65103e",
  "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
  "dataTransformationDefinitionId": "SAP.ODM",
  "externalIdColumn": "BP_EXTERNAL_ID",
  "featureOn": [
    "UPSERT_BY_EXTERNAL_ID"
  ],
  "result": {
    "statistics": { … }
  }
}

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

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

Data Exchange API (5)

Seed Updates

Analytics

Business Partner Storages

Business Partners

Data Import

Start Import Job

Request

Responses

Share the feedback!

Poll Import Job

Request

Responses

Share the feedback!

Data Mapping

Data Monitors

Data Transformation

DNB Storages

Files

Data Mappers

Relations

Subscriptions