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": "third"
    }
  ]
}

orderable: true means connected and orderable now; false means the building is in your coverage but still in build-out (pre-order territory). line_type is the building’s line type: first, second, third, or null when the building is not classified yet. earliest_service_date is the building’s planned occupancy date while it is still ahead: a customer’s move-in date cannot be earlier, and checkout refuses one that is. On a first-line building, a kurnl checkout with a later move-in date holds the order and starts it on that day. presale: true marks a build-out building opened for pre-orders; it may now be a first-line building.

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,
  "presale": false,
  "bulk": false,
  "earliest_service_date": null,
  "match": {
    "building_id": "3a0f…",
    "address": "12 Wharf St",
    "city": "Victoria",
    "postal_code": "V8V 1A1",
    "province": "BC",
    "country": "Canada",
    "status": "live",
    "orderable": true,
    "line_type": "third"
  },
  "plans": [
    {
      "plan_version_id": "9c2e…",
      "name": "Bolt 500",
      "download_mbps": 500,
      "upload_mbps": 500,
      "retail_price_monthly": 49.0,
      "is_bulk": false
    }
  ],
  "hits": 1,
  "parsed": { "postal": "V8V1A1", "house_number": "12", "street_tokens": ["wharf"] }
}

Field	Meaning
`serviceable`	The address is inside your coverage and your provider has a plan selection there or offers an external plan. A normal building you cover but have chosen no plans for is not serviceable; a Bulk Deal building stays serviceable with its fixed plans.
`orderable`	Connected now — an order can proceed.
`preorder`	In your coverage but still in build-out.
`presale`	Narrows `preorder`: the operator opened the building for pre-orders.
`bulk`	`true` when the building includes internet in the rent. A bulk building offers only bulk plans; see `plans`.
`earliest_service_date`	ISO date service can start at this building — its planned occupancy date while that is still ahead — or `null`. A move-in date before it is refused at checkout. On a first-line building the order then starts on that day (kurnl’s own checkouts).
`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 — only the plans you offer at this building (advisory display snapshot — pricing is authoritative at checkout). A plan faster than the building delivers per line (its speed tier) is not listed, and ordering it is refused with `422 speed_tier`. A plan for existing customers only is not listed either, and ordering it is refused with `422 plan_audience`. A plan your provider does not offer at this building is not listed, and ordering it is refused with `422 plan_not_offered`. Each plan carries `is_bulk`. In a bulk building (`bulk: true`) `plans` holds only your bulk plan versions, at `"retail_price_monthly": 0.0`; show them as included in the rent, not as a $0 offer. A paid plan ordered there, or a bulk plan ordered anywhere else, is refused with `422 bulk_plan`.
`parsed`	How the input was interpreted — useful when debugging a non-match.

Example of a bulk building (bulk: true):

{
  "serviceable": true,
  "orderable": true,
  "bulk": true,
  "plans": [
    {
      "plan_version_id": "4d7b…",
      "name": "Bolt 500 (included)",
      "download_mbps": 500,
      "upload_mbps": 500,
      "retail_price_monthly": 0.0,
      "is_bulk": true
    }
  ]
}

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", "postal_unit": null, "available": true, "cpe_ready": true },
    { "id": "7d12…", "unit_number": "102", "floor": "1", "postal_unit": null, "available": false, "cpe_ready": false },
    { "id": "7d13…", "unit_number": "200-1", "floor": "2", "postal_unit": "200", "available": true, "cpe_ready": false }
  ]
}

Field	Meaning
`id`	The `unit_id` to send to provider-initiated provisioning.
`unit_number` / `floor`	For display in your picker.
`postal_unit`	The suite’s postal label (`"200"`) when the suite has several connections (`200-1`, `200-2`, …); `null` for a unit that is alone in its suite. Show it as the suite number.
`available`	`false` when an order already exists for that unit — for a suite with several connections, `false` only when every connection is taken (has an order, or is not free to be connected).
`cpe_ready`	`true` when the suite’s router is already online (it answered within the last 15 minutes) — on a second- or third-line building an order there is provisioned at once, without a visit. Always `false` for a suite with several connections. It describes the suite, not the building: on a first-line building every suite is provisioned anyway, and on an unclassified building (`line_type: null`) an order takes the install path even when it is `true`. A snapshot: a router can go offline before the order, and the order then takes the install path — read `route` in the order response. `false` also when kurnl cannot read the router’s state.

A suite with several connections is one entry, not one per connection. Its id and unit_number are those of the suite’s first free connection, by the same rule an order on the suite is placed by (the first one when none is free), so the id can be a different connection than the one listed on an earlier call. Send that id as unit_id — kurnl re-anchors the order to a free connection itself (see provider-initiated provisioning).

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