Provider-Initiated Provisioning (PAY-03)

See Subscriber Management for the full guide.

Endpoint

POST /partner/provisioning/provider-initiated

Auth: X-API-Key
Rate limit: 120 requests / minute

When to use

PAY-03 is for ISP-initiated provisioning — you have the subscriber’s details (from your own storefront, a sales CRM, a signed contract, or a migration from another system) and want to create their account without redirecting them through a kurnl checkout flow. You can name the premise two ways:

`delivery_mode`	You send	Use when
`direct` (default)	`location_hash` or `location_identifier`	You know the physical port — a migration with mapped records, or a subscriber already detected on the network.
`home_drop`	`unit_id`	Your storefront asked the customer for their address and suite. Get the `unit_id` from `GET /serviceability/units`.

delivery_mode states what you have; it does not choose the outcome. The building’s line type decides whether kurnl provisions a port immediately or raises an install job for a technician, and a request that does not fit the building is refused with 422 rather than half-completed. Read route in the response to find out which happened.

Request body

{
  "plan_version_id": "uuid",
  "delivery_mode": "direct | home_drop (optional, default \"direct\")",
  "location_hash": "10-char hex (direct; preferred)",
  "location_identifier": "string (direct; legacy alternative)",
  "unit_id": "uuid (home_drop)",
  "subscriber": {
    "email": "string",
    "username": "string (min 3 chars)",
    "password": "string (optional, min 8 chars)",
    "customer_type": "RESIDENTIAL | BUSINESS",
    "mac_address": "string (optional)",
    "invoice_contact_detail": {
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "phonenumber": "string (optional)",
      "company": "string (optional)"
    },
    "contract_contact_detail": {
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "phonenumber": "string (optional)",
      "company": "string (optional)"
    },
    "invoice_address": {
      "street": "string",
      "housenumber": "string",
      "postalcode": "string",
      "city": "string",
      "province": "string",
      "country": "Canada",
      "unitnumber": "string (optional)",
      "floor": "string (optional)"
    }
  }
}

With delivery_mode: "direct" (the default) provide at least one of location_hash or location_identifier (both is legal; location_hash wins). With delivery_mode: "home_drop" provide unit_id instead; location fields are ignored. There are no top-level subscriber.firstname / lastname / phonenumber fields — names and phone numbers live in invoice_contact_detail / contract_contact_detail. subscriber.password is optional; when set it controls the subscriber’s self-service login.

Response — 200 OK

{
  "job_id": "uuid or null",
  "subscription_id": "uuid",
  "subscriber_id": "uuid",
  "message": "Provisioning started",
  "route": "provision | install"
}

Field	Meaning
`route`	`provision` — the port is being configured now. `install` — the subscription is `PENDING_INSTALL` and an operator install job was raised; a technician completes it with `POST /provisioning/confirm-install`.
`job_id`	The background switch job. `null` on the `install` route (there is no job yet), and an empty string on an idempotent replay — so branch on `route`, never on `job_id`.

Your confirmation screen should differ between the two: provision means the customer is coming online now, install means someone will contact them to book a visit. Webhooks: subscription.activated fires immediately at subscription creation — before the port is live. provisioning.completed (or provisioning.failed) fires after the background job finishes.

Idempotency

Idempotency is scoped to the exact (subscriber, plan version, location) triple — the same email + plan at a different location provisions normally (a genuine second line). SUSPENDED subscriptions count as live for this check. A replayed request returns 200 with the existing subscription:

{
  "job_id": "uuid or \"\"",
  "subscription_id": "uuid",
  "subscriber_id": "uuid",
  "message": "Provisioning already in progress"
}

message is "Provisioning already in progress" when a provisioning job is still pending/running, or "Subscription already exists (idempotent replay)" otherwise. job_id may be the empty string when no job record exists. Safe to retry on network errors.

Error codes

Status	Detail
`400`	`"Plan version not active"` / `"Plan version not yet active"`
`400`	`"Location '…' has no switch"`
`400`	`"Cannot parse port from interface '…'"`
`400`	`"Service provider has no VLAN configured"`
`400`	`"VLAN '…' is not a valid integer"`
`400`	`"Plan version missing download_speed_mbps"`
`401`	Missing or invalid `X-API-Key`
`403`	`"Plan version does not belong to your service provider"`
`403`	`"API access is not enabled for this account"`
`404`	`"Plan version {id} not found"` / `"Location not found for location_hash"` / `"Location '…' not found"`
`404`	`"Unit '…' not found"`
`422`	`"Invalid location_hash format"`
`422`	The request does not fit the building’s line type — e.g. a `direct` order on a building that requires a technician visit. The message names what is missing.
`422`	`"unit_id is required when delivery_mode is 'home_drop'"`
`422`	Model validation (missing fields, bad email format, neither location field)
`429`	Rate limit exceeded (120/min)
`500`	`"Provisioning failed"` (unexpected error; partial creates are rolled back)
`502`	Inconsistent upstream data (e.g. plan version missing its service provider)

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

Provider-Initiated Provisioning (PAY-03)

Endpoint

When to use

Request body

Response — 200 OK

Idempotency

Error codes

​Endpoint

​When to use

​Request body

​Response — 200 OK

​Idempotency

​Error codes

Endpoint

When to use

Request body

Response — 200 OK

Idempotency

Error codes