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` = Business Partner External ID	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`	Business Partner 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`	Business Partner 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`	Business Partner 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`	Business Partner 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`	Business Partner 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`	Business Partner 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)	Business Partner 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` = `PO BOX` in `$.addresses\[0\]` in France, in `$.addresses\[1\]` for non-France	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 stringifies 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.

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

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:"2026-10-21T13:37:19Z"

modifiedAtstring(ModifiedAt)

Date of modification (ISO 8601-compliant).

Example:"2026-10-21T13:37:19Z"

progressinteger, [ 0 .. 100 ](JobProgress)

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.
CANCELED	Job has been canceled due to invalid input configuration.
FAILED	Job has failed.

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"

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.

resultobject(ImportJobResult)

The result of the Import Job.

domainstring(Domain)deprecated

Domain of a Business Partner Storage.

Example:"BusinessPartner"

Response

{
  "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": "2026-10-21T13:37:19Z",
  "modifiedAt": "2026-10-21T13:37:19Z",
  "progress": "77",
  "status": "RUNNING",
  "statusMessage": "The job failed because storage is empty.",
  "storageId": "72d6900fce6b326088f5d9d91049e3e6",
  "dataSource": "648824a691d8d2503d65103e",
  "dataMapperDefinitionId": "6440dba32b30176c5917b1b7",
  "externalIdColumn": "BP_EXTERNAL_ID",
  "featureOn": [
    "UPSERT_BY_EXTERNAL_ID"
  ],
  "result": {
    "statistics": { … }
  }
}

Start Import Job

Request

Responses

Share the feedback!