Availability and offers

check_availability can return address-resolution progress, FCC-reported coverage, live provider qualification, or more than one of those at once. Preserve each useful result and its provenance.

FCC evidence is area-level

An FCC match means a provider reported serving the returned census block or tract as of the returned data date. It does not prove that the provider will serve the exact address, that the provider currently sells every listed plan, or that the FCC list is exhaustive. Describe it as reported coverage in the returned area. Do not say “available at this address” based only on FCC data.

Live qualification is asynchronous

A live provider check attempts to qualify the resolved address. Its state is separate from the FCC state and can change across lookup revisions.

Live source state	Client behavior
`checking`	Present any FCC findings and other finished evidence. Wait for `retry_after_seconds`, then poll the same `lookup_id`.
`needs_information`	Ask only the current typed questions and submit the complete required answer set.
`complete`	Present live-qualified provider facts and executable offers, if any.
`failed`	Keep any FCC findings. Explain that live qualification failed and follow `next_action`; do not claim no service.
`timed_out`	Keep any FCC findings. Explain that the live check did not finish in time and follow `next_action`; do not claim no service.

Polling reads the current snapshot. Starting again with the address creates a separate lookup and can discard useful progress.

Common result combinations

Evidence returned	What it supports	What it does not support
FCC and live both match	The provider reported area coverage and Hum obtained current live qualification.	ISP acceptance or installation confirmation.
FCC only; live checking	Area coverage can be shown while live work continues.	Exact-address service or “no offers.”
FCC only; live failed or timed out	Area coverage can still be useful, with the live failure disclosed.	A no-service conclusion.
Live only	Hum obtained live qualification even though no matching FCC fact is present.	A claim about FCC coverage.
Live needs information	The provider requires the returned answer set before qualification can continue.	Permission to infer or default an answer.
Both sources complete with no executable offer	The returned evidence and informational plans can be shown.	An orderable selection or a broader claim that no service exists.

Use the top-level status, both source states, warnings, and next_action together. An empty offers array is not a general no-service signal.

Address clarification

Hum can return up to five normalized candidates instead of silently choosing one. Show each candidate’s display value and ask the user to select it. Return its exact candidate_id. If the chosen candidate has requires_unit: true or the result requests unit, ask for that unit and continue with {candidate_id, unit}. Do not guess a unit, alter a candidate ID, or replace the candidate continuation with a new free-form address. Candidate and lookup IDs are opaque scoped capabilities. Do not show them as user-facing order or provider identifiers.

Qualification questions

Each question contains:

question_id: the key to use in answers
prompt: the text to present
type: string, boolean, single_choice, or date
choices: allowed values for a single-choice question
required: whether an answer is required
sensitivity: none, personal, or sensitive

Ask the current set and send the required answers together with the exact question_set_id. Do not invent an answer, select a default, answer a stale question set, or include extra answer keys. Apply the host’s normal information-access and user-interaction policies when collecting answers.

Provider provenance and freshness

A provider’s provenance can include fcc, live_provider_check, or both. Present the provenance with the relevant data_as_of, checked_at, qualified_at, and expires_at fields. Do not combine facts from different revisions into an apparently current offer. qualification_status is evidence about Hum’s qualification process. It is not an order or installation status.

Informational plans and executable offers

A provider can return two plan collections:

Collection	Purpose	Can be ordered?
`catalog_plans`	Informational plan facts that help explain possible service.	No.
`offers`	Live-qualified selections bound to the current lookup revision and expiry.	Yes, when the offer has `orderable_through_hum: true`.

An executable offer includes:

exact offer_id and provider_id
qualification_revision
qualified_at and expires_at
orderable_through_hum: true
returned plan, pricing, fee, contract, data-limit, and condition facts

Pass only the returned offer_id to validate_order. Never derive an ID from a plan name, send a catalog plan ID, or substitute a similar offer.

Unknown facts

Prices and fees are integer cents with a currency code. A null field is unknown, not zero. Preserve unknown values for:

current and regular monthly price
promotion length
self or professional installation fee
activation or recurring equipment fee
contract requirement and duration
download or upload speed
data limit and other conditions

Validation may refresh these facts. If the offer changes, present the new review and obtain a new decision before submission. See Ordering and recovery.

​Availability and offers

​FCC evidence is area-level

​Live qualification is asynchronous

​Common result combinations

​Address clarification

​Qualification questions

​Provider provenance and freshness

​Informational plans and executable offers

​Unknown facts