> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datawiz.io/connector-api/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration flow

> Step-by-step upload and Connector workflow

## Step 1. Initialize session

```bash theme={null}
curl -X POST https://<host>/api/v1/uploading/initialize-session \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"
```

Success response:

```json theme={null}
{ "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`              |
| Connector running (`STARTED`) | `409` | `workflow_running` | Wait or call `terminate`                              |
| Previous session `DONE`       | `200` | `created`          | New session; response includes `previous_upload_uuid` |

## Step 2. Upload entities

```bash theme={null}
curl -X POST https://<host>/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](/connector-api/integration/entity-upload).

## Step 3. Check session status

```bash theme={null}
curl https://<host>/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 Connector

```bash theme={null}
curl -X POST https://<host>/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 background S3 writes are still running → `409 Upload tasks are still in progress`. Retry after `upload_tasks_finished = true`.

## Step 5. Wait for Connector completion

No extra client requests are required. Connector notifies the service automatically. Poll `GET /status` until `session_status = DONE`.

## Terminate Connector

```bash theme={null}
curl -X POST https://<host>/api/v1/uploading/b3f1...c9/terminate \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"
```

Available only in `STARTED` state. The API asks Connector to stop; the session returns to `UPLOADING` only after Connector sends the completion webhook with `is_terminated=true`. Poll `GET /status` until `session_status = UPLOADING` before uploading again.

If the session is not `STARTED`:

```json theme={null}
{"detail": "Workflow is not running"}
```

HTTP status: **`404 Not Found`**.

## Delete upload

```bash theme={null}
curl -X POST https://<host>/api/v1/uploading/b3f1...c9/delete \
  -H "Authorization: <token>" \
  -H "Client-Id: 42"
```

Available only in `UPLOADING`. File deletion 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`**:

```json theme={null}
{
  "detail": {
    "message": "Invalid upload session status",
    "expected": "UPLOADING",
    "actual": "DONE"
  }
}
```

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