Bulk Provisioning

When to use this

Bulk provisioning is designed for:

Migrations — moving a large subscriber base from another platform to kurnl
New building activations — activating an entire MDU building at once when all units are pre-wired
Batch imports — provisioning a list of new subscribers from a CSV or external system

For single subscribers, use CKO-04 provider-initiated or CKO-03 instead.

How it works

Bulk provisioning is asynchronous. You submit a batch, kurnl returns a batch_id immediately, and provisioning runs in the background. You poll the batch status endpoint to track progress.

Submit a batch

curl -X POST https://middleware.bso-projects.com/partner/provisioning/bulk \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribers": [
      {
        "plan_version_id": "f7e8d9c0-...",
        "location_hash": "ab12cd34ef",
        "email": "alice@example.com",
        "firstname": "Alice",
        "lastname": "Smith",
        "street": "Maple St",
        "housenumber": "42",
        "postalcode": "A1B 2C3",
        "city": "Vancouver",
        "province": "BC"
      },
      {
        "plan_version_id": "f7e8d9c0-...",
        "location_hash": "cd34ef5678",
        "email": "bob@example.com",
        "firstname": "Bob",
        "lastname": "Jones",
        "street": "Oak Ave",
        "housenumber": "7",
        "postalcode": "B2C 3D4",
        "city": "Victoria",
        "province": "BC"
      }
    ]
  }'

Response — 202 Accepted:

{
  "batch_id": "batch-uuid-...",
  "total": 2,
  "message": "Batch queued"
}

Poll for status

curl https://middleware.bso-projects.com/partner/provisioning/bulk/{batch_id} \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "batch_id": "batch-uuid-...",
  "status": "in_progress",
  "total": 2,
  "completed": 1,
  "failed": 0,
  "results": [
    {
      "email": "alice@example.com",
      "status": "completed",
      "subscription_id": "8c4a1b9e-...",
      "subscriber_id": "2f5d7a0c-...",
      "job_id": "3d6e8f12-..."
    },
    {
      "email": "bob@example.com",
      "status": "pending"
    }
  ]
}

Poll every 5–10 seconds until status is "completed" or "completed_with_errors".

Handling partial failures

Individual subscriber failures don’t stop the rest of the batch. If a subscriber fails (e.g. invalid location hash, duplicate subscription), their entry in results shows "status": "failed" with an "error" field.

{
  "email": "carol@example.com",
  "status": "failed",
  "error": "Location not found for location_hash"
}

After the batch completes, handle failed entries individually — fix the error (e.g. correct the location hash) and resubmit just those subscribers.

Limits

Limit	Value
Max subscribers per batch	100
Concurrent batches	3
Batch result retention	48 hours

If you need to provision more than 100 subscribers, split them into multiple batches. You can submit the next batch as soon as the previous one is accepted (you don’t need to wait for completion).

Migration checklist

Before running a bulk migration:

Map location hashes

Every subscriber needs a valid location_hash corresponding to a kurnl switch port. Work with your kurnl account manager to get a mapping from your building/unit records to kurnl location hashes.

Validate plan versions

Confirm your plan_version_id values are active. Expired plan versions will cause the entire subscriber entry to fail.

Test with a small batch

Run a batch of 3–5 subscribers first and verify they provision correctly before running the full migration.

Run in off-peak hours

Large batches generate significant switch SSH traffic. Schedule migrations during low-traffic periods.

Handle failed entries

After the batch completes, process failed entries individually. Log the errors, fix the root cause, and resubmit.

Getting Started

Operator Guides

Integration Guides

AI Support Agent

When to use this

How it works

Submit a batch

Poll for status

Handling partial failures

Limits

Migration checklist

​When to use this

​How it works

​Submit a batch

​Poll for status

​Handling partial failures

​Limits

​Migration checklist

When to use this

How it works

Submit a batch

Poll for status

Handling partial failures

Limits

Migration checklist