Integration flow

Step 1. Initialize session

curl -X POST https://connector-api.datawiz.io/api/v1/uploading/initialize-session \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"

Success response:

{ "status": "created", "upload_uuid": "b3f1...c9", "message": "Upload session created" }

Repeated calls

Situation	HTTP	`status`	Action
No active session	`200`	`created`	Use the returned `upload_uuid`
Session in `UPLOADING`	`409`	`already_exists`	Continue with the existing `upload_uuid`
Data loading in progress (`STARTED`)	`409`	`workflow_running`	Wait or call `terminate`
Previous session `DONE`	`200`	`created`	New session; response includes `previous_upload_uuid`

Step 2. Upload entities

curl -X POST https://connector-api.datawiz.io/api/v1/uploading/b3f1...c9/receipt \
  -H "Authorization: <token>" \
  -H "Client-Id: 42" \
  -H "Content-Type: application/json" \
  -d @payload.json

Payload format: Entity upload. Uploaded packages are validated and collected in the session. They wait until you start data loading.

Step 3. Check session status

curl https://connector-api.datawiz.io/api/v1/uploading/b3f1...c9/status \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"

Poll GET /status after ingest until can_start_upload = true, and after start-upload until session_status = DONE.

Step 4. Start data loading

curl -X POST https://connector-api.datawiz.io/api/v1/uploading/b3f1...c9/start-upload \
  -H "Authorization: <token>" \
  -H "Client-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{ "date_from": "2026-06-01", "date_to": "2026-06-29" }'

Date range rules:

date_from ≤ date_to
date_to must be before today
date_from cannot be earlier than the client minimum date configured on the server

If previously uploaded packages are still being prepared → 409 Upload tasks are still in progress. Retry after upload_tasks_finished = true.

Step 5. Wait for completion

Progress of data loading is tracked via GET /uploading/{upload_uuid}/status. Poll this endpoint until session_status = DONE. You can also:

optionally receive an email when data loading finishes (configure with support);
check the status in the UI at data-console.datawiz.io.

Terminate data loading

curl -X POST https://connector-api.datawiz.io/api/v1/uploading/b3f1...c9/terminate \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"

Available only in STARTED state. The API requests cancellation; the session returns to UPLOADING only after loading stops. Poll GET /status until session_status = UPLOADING before uploading again. If the session is not STARTED:

{"detail": "Workflow is not running"}

HTTP status: 404 Not Found.

Delete upload

curl -X POST https://connector-api.datawiz.io/api/v1/uploading/b3f1...c9/delete \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"

Available only in UPLOADING. Deletion of collected data is asynchronous. Start a new cycle with initialize-session. If the session is not UPLOADING (e.g. DONE or STARTED), the API returns 409 Conflict:

{
  "detail": {
    "message": "Invalid upload session status",
    "expected": "UPLOADING",
    "actual": "DONE"
  }
}

For a DONE session, use initialize-session instead of delete.

Getting started

Integration

Reference

API Reference

Step 1. Initialize session

Repeated calls

Step 2. Upload entities

Step 3. Check session status

Step 4. Start data loading

Step 5. Wait for completion

Terminate data loading

Delete upload

​Step 1. Initialize session

​Repeated calls

​Step 2. Upload entities

​Step 3. Check session status

​Step 4. Start data loading

​Step 5. Wait for completion

​Terminate data loading

​Delete upload

Step 1. Initialize session

Repeated calls

Step 2. Upload entities

Step 3. Check session status

Step 4. Start data loading

Step 5. Wait for completion

Terminate data loading

Delete upload