Start a data import

Starts a bulk import from one or more uploaded data files. Use this as the first step of a migration: pick the record type you are importing, upload the file(s), and receive an identifier you can use to track progress and review errors.

The import runs in the background — the response returns immediately with an identifier, not the final result.

The record type is chosen with the migration_key in the path; each type has its own set of columns:

• user — customer accounts, with login credentials (columns: UserImportRow)

• address — delivery/billing addresses of migrated customers (columns: AddressImportRow)

• order — historical orders of migrated customers (columns: OrderImportRow)

• order_item — line items of migrated orders (columns: OrderItemImportRow)

• retail_store — physical stores (columns: RetailStoreImportRow)

Each uploaded file must be tabular, with one record per row and the columns listed for the chosen record type. Multiple files may be uploaded together. Import options can be supplied in the params field (see ImportOptions).

post

/migrations/start/{migration_key}/

Authorizations

AuthorizationstringRequired

Token credential sent in the Authorization header, in the form: Token <your-token>. Requires a staff (admin) account.

Path parameters

migration_keystring · enumRequired

The type of record to import.

Possible values:

Body

filesstring · binary[]Required

One or more tabular data files. Each row is one record; columns must match the fields of the chosen record type. At least one file part is required, but the form-part name itself is not significant — every uploaded file is processed regardless of the field name used (it need not literally be files).

paramsstringOptional

Optional JSON object (sent as a string) with import options. See the Import options schema for the available settings.

Example: {"allow_empty_phone": true}

Responses

200

The import has been queued. Use the returned identifier to track it.

application/json

migration_idstringOptional

Identifier of the started import.

Example: 3f2a1c9e8b7d4a6f9c0e1d2b3a4c5e6f

400

The request could not be accepted — for example an unknown record type, or no data file was uploaded. Individual rows are validated while the import runs, not here; row-level problems appear via the errors endpoint.

401

Authentication credentials were missing or invalid.

403

The account does not have staff (admin) permission.

406

The import options could not be read as JSON.

application/json

post/migrations/start/{migration_key}/

POST /api/remote/1/migrations/start/{migration_key}/ HTTP/1.1
Host: sandbox.akinon.com
Authorization: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 61

{
  "files": [
    "binary"
  ],
  "params": "{\"allow_empty_phone\": true}"
}

{
  "migration_id": "3f2a1c9e8b7d4a6f9c0e1d2b3a4c5e6f"
}