​
Overview

The subscriber management API lets you manage the full subscriber lifecycle from your own back-office system. All endpoints use X-API-Key authentication and are scoped to your provider account — you cannot read or modify another provider’s subscribers.

​
Create a subscriber

To create a subscriber without immediately provisioning a port, use the subscriber create endpoint. This is useful when you want to register a subscriber in kurnl before their service is ready. 
curl -X POST https://api.kurnl.ca/api/v1/provider/subscribers \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dave@example.com",
    "firstname": "Dave",
    "lastname": "Brown",
    "phonenumber": "+17785550001",
    "street": "Cedar Lane",
    "housenumber": "15",
    "postalcode": "D4E 5F6",
    "city": "Kamloops",
    "province": "BC"
  }'
If a subscriber with the same email already exists in your provider account, the existing subscriber is returned rather than creating a duplicate. Subscriber creation is idempotent by email.

​
List your subscribers

curl https://api.kurnl.ca/api/v1/provider/subscribers \
  -H "X-API-Key: YOUR_API_KEY"
Supports pagination with ?page=1&page_size=50 and filtering with ?status=active or ?search=dave@example.com.

​
Get a single subscriber

curl https://api.kurnl.ca/api/v1/provider/subscribers/{subscriber_id} \
  -H "X-API-Key: YOUR_API_KEY"
The response includes the subscriber’s contact details, address, and a list of their subscriptions.

​
Update subscriber details

curl -X PATCH https://api.kurnl.ca/api/v1/provider/subscribers/{subscriber_id} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phonenumber": "+17785559999",
    "street": "New Street",
    "housenumber": "22"
  }'
All fields are optional. Only provided fields are updated.

​
Manage subscriptions

​
View a subscriber’s subscriptions

curl https://api.kurnl.ca/api/v1/provider/subscribers/{subscriber_id}/subscriptions \
  -H "X-API-Key: YOUR_API_KEY"

​
Activate a subscription

If a subscription is in PENDING state (e.g. created but not yet activated), activate it: 
curl -X POST https://api.kurnl.ca/api/v1/subscription/{subscription_id}/activate \
  -H "X-API-Key: YOUR_API_KEY"

​
Change a subscriber’s plan

curl -X POST https://api.kurnl.ca/api/v1/subscription/{subscription_id}/change-plan \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_version_id": "new-plan-version-uuid"
  }'
kurnl updates the switch port’s VLAN and bandwidth limits to match the new plan. The change takes effect within ~30 seconds.

​
Cancel a subscription

curl -X POST https://api.kurnl.ca/api/v1/subscription/{subscription_id}/cancel \
  -H "X-API-Key: YOUR_API_KEY"
Cancellation:
  • Removes VLAN assignment from the switch port
  • Clears bandwidth limits
  • Resets the port to the captive portal VLAN
  • Marks the subscription as CANCELLED in kurnl
The subscriber record is not deleted. Their login and history are preserved.

​
Subscription statuses

StatusMeaning
PENDINGCreated but not yet activated — waiting for payment or manual activation
PENDING_INSTALLHome-drop — waiting for technician to confirm installation
ACTIVEPort is provisioned and subscriber has internet access
SUSPENDEDPort is throttled or blocked — typically due to overdue payment
CANCELLEDService ended — port has been deprovisioned

​
Deprovision without cancelling

If you want to remove a subscriber’s port access temporarily (e.g. for non-payment) without cancelling the subscription, use the suspend endpoint: 
curl -X POST https://api.kurnl.ca/api/v1/subscription/{subscription_id}/suspend \
  -H "X-API-Key: YOUR_API_KEY"
To restore access: 
curl -X POST https://api.kurnl.ca/api/v1/subscription/{subscription_id}/reactivate \
  -H "X-API-Key: YOUR_API_KEY"

​
Common patterns

​
Migrating existing subscribers

If you’re onboarding an existing subscriber base to kurnl:
  1. Create each subscriber via POST /provider/subscribers
  2. Use CKO-04 / provider-initiated provisioning to activate their port — no marketplace redirect needed
  3. Store kurnl’s subscriber_id and subscription_id in your own system for future management calls

​
Handling a subscriber who moves

  1. Cancel the current subscription (deprovisioning the old port)
  2. Create a new subscription at the new location using the new location_hash
Alternatively, if you know the new location_hash in advance, contact your account manager — a port transfer can be done without cancelling the subscription in some cases.