​
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://api.kurnl.ca/api/v1/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://api.kurnl.ca/api/v1/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

LimitValue
Max subscribers per batch100
Concurrent batches3
Batch result retention48 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:
1

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.
2

Validate plan versions

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

Test with a small batch

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

Run in off-peak hours

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

Handle failed entries

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