Serviceability

Who this is for. These endpoints serve storefronts that run their own checkout funnel and provision through the provider-initiated API — the shopper types an address on your site and you need to know whether, and what, you can sell there. Marketplace-originated external checkout (CKO-03) never uses them: the shopper’s address, building and unit are resolved on the kurnl marketplace, and the checkout session your page reads already carries them.

Endpoints

GET  /partner/serviceability/autocomplete?q=<text>
POST /partner/serviceability/check
GET  /partner/serviceability/units?building_id=<uuid>

Together they are the address funnel: autocomplete turns keystrokes into addresses, check turns one address into a building_id and the plans you can sell there, and units turns that building_id into the premises inside it — the suite a customer picks, which is what provider-initiated provisioning needs when the premise has no live port yet. Auth: X-API-Key: krnl_... on both. Results are automatically scoped to your provider — there is no parameter to query another provider’s coverage, and none is accepted. Rate limits: autocomplete 300 / minute, check 120 / minute, units 300 / minute (per API key).

Serviceability answers are advisory: they come from a coverage index that the kurnl operator refreshes after footprint or plan changes. Checkout and provisioning re-validate every order fail-closed, so a stale index can never place an order at an unserved address — but a very recent footprint change may take until the next index refresh to appear here.

GET /serviceability/autocomplete

Address suggestions for a storefront search box.

Query param	Notes
`q`	Free text. Under 2 non-space characters returns `{"suggestions": []}` (no error).

House-number suffixes may be written fused or separated — 68a and 68 a both match.

Response — 200 OK

At most 15 suggestions, deduplicated by display string:

{
  "suggestions": [
    {
      "display": "12 Wharf St, V8V 1A1 Victoria",
      "building_id": "3a0f…",
      "address": "12 Wharf St",
      "city": "Victoria",
      "postal_code": "V8V 1A1",
      "province": "BC",
      "country": "Canada",
      "status": "live",
      "orderable": true,
      "line_type": "aon"
    }
  ]
}

orderable: true means connected and orderable now; false means the building is in your coverage but still in build-out (pre-order territory).

POST /serviceability/check

Availability verdict for one concrete address.

Request body

Send free text, or structured fields (structured wins when both are present; one of address / street is required, otherwise 422):

{ "address": "Hauptstr. 68a, 29553 Bienenbüttel" }

{
  "street": "Hauptstr.",
  "house_number": "68a",
  "postal_code": "29553",
  "city": "Bienenbüttel"
}

German (5-digit PLZ) and Canadian (A1A 1A1) postal formats are recognized.

A provided house number must match exactly, suffix included — 68a and 68 are different premises. An invented house number on a real street returns serviceable: false.

Response — 200 OK

{
  "serviceable": true,
  "orderable": true,
  "preorder": false,
  "match": {
    "building_id": "3a0f…",
    "address": "12 Wharf St",
    "city": "Victoria",
    "postal_code": "V8V 1A1",
    "province": "BC",
    "country": "Canada",
    "status": "live",
    "orderable": true,
    "line_type": "aon"
  },
  "plans": [
    {
      "plan_version_id": "9c2e…",
      "name": "Bolt 500",
      "download_mbps": 500,
      "upload_mbps": 500,
      "retail_price_monthly": 49.0
    }
  ],
  "hits": 1,
  "parsed": { "postal": "V8V1A1", "house_number": "12", "street_tokens": ["wharf"] }
}

Field	Meaning
`serviceable`	The address is inside your coverage.
`orderable`	Connected now — an order can proceed.
`preorder`	In your coverage but still in build-out.
`match`	The matched building, or `null`. Carry `building_id` into units to let the customer pick their suite.
`plans`	Your plan versions available at this address (advisory display snapshot — pricing is authoritative at checkout).
`parsed`	How the input was interpreted — useful when debugging a non-match.

No match returns 200 with serviceable: false, match: null, plans: [].

GET /serviceability/units

The premises inside one building in your coverage — the suite picker for your checkout page.

Query param	Notes
`building_id`	Required. A `building_id` from `/check` or `/autocomplete`.

Response — 200 OK

{
  "building_id": "3a0f…",
  "units": [
    { "id": "7d11…", "unit_number": "101", "floor": "1", "available": true },
    { "id": "7d12…", "unit_number": "102", "floor": "1", "available": false }
  ]
}

Field	Meaning
`id`	The `unit_id` to send to provider-initiated provisioning.
`unit_number` / `floor`	For display in your picker.
`available`	`false` when an order already exists for that unit.

available is the only occupancy signal, and it is the one to use. A unit is taken when a non-terminal subscription (pending, pending-install or active) references it. Do not infer occupancy from anything else you may have stored about a unit — a suite with an order still in flight looks untouched by every other measure, and offering it again double-books it.

Render unavailable units disabled rather than hiding them: a customer who knows their own suite number is in the building reads a gap in the list as your site being broken.

A building that is not in your coverage returns 404, exactly as an unknown id does. The response never confirms that a building you cannot serve exists.

Errors

Status	Detail
401	Missing or invalid `X-API-Key`
403	API access disabled for your account
404	`units`: building unknown, or outside your coverage
422	Neither `address` nor `street` provided
429	Rate limit exceeded
503	Serviceability search not configured or temporarily unavailable — retry later; do not treat as “not serviceable”

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

Endpoints

GET /serviceability/autocomplete

Response — 200 OK

POST /serviceability/check

Request body

Response — 200 OK

GET /serviceability/units

Response — 200 OK

Errors

​Endpoints

​GET /serviceability/autocomplete

​Response — 200 OK

​POST /serviceability/check

​Request body

​Response — 200 OK

​GET /serviceability/units

​Response — 200 OK

​Errors

Endpoints

GET /serviceability/autocomplete

Response — 200 OK

POST /serviceability/check

Request body

Response — 200 OK

GET /serviceability/units

Response — 200 OK

Errors