--- title: "Get Internet Service Availability" method: GET path: "/sessions/{token}/services/internet" tags: ["Service Availability"] --- # Get Internet Service Availability `GET /sessions/{token}/services/internet` Retrieves available Internet service providers and their offerings for the service address associated with the current session. ## Data Provided - Internet Service Providers (ISPs) - Available plans and pricing - Technology types (Fiber, Cable, DSL, etc.) - Maximum speeds - Provider contact information - Checkout URLs ## Data Freshness Provider and product data comes from the current Hum data set identified by `meta.hum_data_set`. ## Example Response ```json { "message": "Service coverage for 29090 TIFFANY DR E, SOUTHFIELD, MI 48034", "request_status": "ok", "data": [ { "provider_id": "130317", "provider_name": "Xfinity", "telephone": "+18332981431", "provider_icon": null, "provider_logo": "https://cdn.example.com/providers/xfinity-logo.png", "url": "https://affiliate.example.com/xfinity?session=SESSION_TOKEN", "button_label": "xfinity.com", "min_plan_price": { "amount_cents": 4000, "currency": "USD" }, "provider_promo": {}, "url_promo": {}, "offerings": [ { "technology": "Cable", "max_download_speed": 1200, "max_upload_speed": 35 } ], "product_catalog": [] } ], "meta": { "session_token": "SESSION_TOKEN_PLACEHOLDER", "session_status": "open", "session_params": { "street1": "29090 Tiffany Dr E", "street2": null, "city": "Southfield", "state": "MI", "zip": "48034", "latitude": "42.50189", "longitude": "-83.29528", "campaign_id": null }, "service_address": "29090 Tiffany Dr E, Southfield, MI 48034-4540", "mdu": false, "agent_status": { "geocoding": "matched", "internet": "matched", "checkout": "pending" }, "created_at": "2026-07-13T12:26:15.618-04:00", "updated_at": "2026-07-13T12:26:15.618-04:00", "responded_at": "2026-07-13T16:26:17.471Z", "hum_data_set": "26011015" } } ``` Note: Some providers may return an empty `product_catalog` array. ## Response `200` Internet service providers, available plans, and logos/urls for a given service address. - object - `message` string, required — A message returned by the API. Includes a human-readable message about the status of the request. - `request_status` 'ok' | 'warning' | 'error', required — An informational summary returned in API response bodies: `ok` for successful responses, `warning` for standard request errors, and `error` for endpoint-specific failures. Integrations must use the HTTP status code, not `request_status`, to determine whether a request succeeded. - `qualify_status` 'available' | 'no_service' | 'pending' | 'failed' | 'retry_later' — The status of Internet service qualification for the address distinguishes a completed lookup from one that is not ready yet. **The answer is ready:** - `available`: Providers were found and are returned in `data`. - `no_service`: No providers serve this address. `data` is `[]`. You can act on this now, but Hum re-checks periodically, so re-validate it if you store it long term. **The answer is not ready, keep polling:** - `pending`: The lookup has not finished. `data` is `[]`. Retry by polling `GET /sessions/{token}/services/internet`. - `retry_later`: A transient upstream problem. `data` is `[]`. Retry by polling `GET /sessions/{token}/services/internet`. **Something went wrong:** - `failed`: The lookup errored for this address. `data` is `[]`. A `pending` lookup finishes as one of three values: `available` when providers are found, `no_service` when the lookup completes and finds none, or `failed` when it errors. `retry_later` arises separately and does not follow from `pending`. These three values should end the polling loop. - `data` ProviderOffering[], required - `provider_id` string, required — FCC provider identifier - `provider_name` string, required — The name of the Internet service provider. - `telephone` string, nullable, required — The telephone number associated with the record. - `provider_icon` string, uri, nullable, required — URL for the provider icon image - `provider_logo` string, uri, nullable, required — The logo of the service provider. - `url` string, uri, required — URL for accessing the provider website through Hum's tracking system - `button_label` string, required — The text to display on the provider's call-to-action button - `min_plan_price` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `provider_promo` object, nullable, required — Provider-level promotional information - `promo_text` string, nullable — Promotional text from the provider - `promo_logo` string, nullable — Promotional logo identifier - `promo_logo_url` string, uri, nullable — URL for the promotional icon image - `url_promo` object, nullable, required — URL/buyflow-specific promotional information - `promo_text` string, nullable — Promotional text specific to this URL/technology - `promo_logo` string, nullable — Promotional logo identifier - `promo_logo_url` string, uri, nullable — URL for the promotional icon image - `offerings` object[], required - `technology` 'Fiber' | 'Cable' | 'DSL' | 'Satellite' | 'Wireless' | 'Other', required — The technology used to deliver the service. - `max_download_speed` integer, required — The advertised maximum download speed in Mbps. - `max_upload_speed` integer, required — The advertised maximum upload speed in Mbps. - `product_catalog` object[], required — Array of product categories, each containing detailed product offerings from this provider - `category` 'internet' | 'internet_add_on' | 'mobile' | 'television' | 'television_add_on' | 'telephone', required — Category identifier - `category_name` string, required — Human-readable category name - `category_description` string, required — Description of the category - `products` object[], required - `id` string, uuid, required — Unique product identifier - `sku` string, required — Product SKU - `name` string, required — Product name - `category` string, required — Product category - `category_name` string, required — Human-readable category name - `technology` 'cable' | 'fiber' | 'dsl' | 'satellite' | 'wireless' | 'not_applicable', required — Technology used for this product - `position` integer, required — Display position within category - `select_type` 'radio' | 'checkbox', required — How this product should be displayed in UI - `description` string, required — Product description - `download_speed` string, nullable, required — Download speed in Mbps. Single value (e.g., '400') or hyphen-delimited range (e.g., '50-100') - `upload_speed` string, nullable, required — Upload speed in Mbps. Single value (e.g., '169') or hyphen-delimited range (e.g., '10-25') - `data_limit` string, required — Data limit display - either GB amount (e.g., "50 GB") or "Unlimited" - `channel_count` integer, required — Number of TV channels (for TV products) - `streaming_apps` string[], required — Included streaming apps - `is_required_to_checkout` boolean, required — Whether this product is required for checkout - `is_contract_required` boolean, required — Whether a contract is required for this product - `is_modem_router_included` boolean, required — Whether modem/router is included with this product - `is_bundle_qualifier` boolean, nullable, required — Whether this product qualifies for bundle discounts - `bundle_discounts` object, required — Bundle discount information - `is_local_checkout` boolean, required — Whether checkout is available locally - `required_with_plans` string[], required — Plans that this product is required with - `included_with_plans` string[], required — Plans that include this product - `only_available_with_plans` string[], required — Plans that this product is only available with - `initial_term_discount_months` integer, required — Number of months for initial term discount - `second_term_discount_months` integer, nullable, required — Number of months for second term discount - `hum_rank` integer, nullable, required — Hum rank score for this product (0-100, higher is better) - `max_quantity` integer, required — Maximum quantity allowed for this product - `product_promo` object, required — Product-level promotional information - `promo_text` string, nullable — Promotional text for this product - `promo_logo_url` string, uri, nullable — URL for the promotional icon image - `info` string, required — Additional product information - `pricing` object, required — Detailed pricing breakdown for this product - `extra_data_fee` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `professional_installation_fee` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `self_installation_fee` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `activation_fee` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `initial_term_discount` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `second_term_discount` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `third_term_discount` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `autopay_discount` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `paperless_billing_discount` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `combined_autopay_paperless_discount` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `net_monthly_price` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `gross_monthly_fee` Money, required - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999. - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars. - `meta` Meta, required — Session metadata, including normalized input values, formatted service address, session status, and the Hum data set used for the response. - `session_token` string, required — The session token provided by the Hum API. Used to connect the response to the session in the client system. - `session_status` 'open' | 'closed', required — The status of the session. - `agent_status` AgentStatus, required - `geocoding` 'pending' | 'matched' | 'multiple' | 'failed' — The status of the geocoding agent. Pending: The agent has not yet processed the address. Matched: The agent has found a single match for the address. Multiple: The agent has found multiple matches for the address. Failed: The agent was unable to match the address. - `internet` 'pending' | 'matched' | 'failed' — The status of the Internet service availability agent. Pending: The agent has not yet processed the address. Matched: The agent has found Internet service providers for the address. Failed: The agent was unable to find Internet service providers for the address. - `checkout` 'pending' — The status of the checkout agent. Pending: The agent has not yet begun processing a checkout for service. - `session_params` NormalizedSessionParams, required — Address and campaign values after normalization. Coordinate values are serialized as strings in response metadata. - `street1` string, required - `street2` string, nullable, required - `city` string, required - `state` string, required - `zip` string, required - `latitude` string, nullable, required - `longitude` string, nullable, required - `campaign_id` string, nullable, required - `service_address` string, required — The complete service address as a single string. - `mdu` boolean, required — Whether the normalized service address is a multi-dwelling unit. - `created_at` string, date-time, required — The timestamp when the session was created. - `updated_at` string, date-time, required — The timestamp when the session was last updated. - `responded_at` string, date-time, required — The timestamp when the response was generated. - `hum_data_set` string, required — The version of the Hum data set used to generate the response. This version may change as the data set is updated. ## Other responses - `400` — Bad request. This includes an invalid session token. Use the HTTP status code, not `request_status`, to detect the error. - `401` — Unauthorized. Use the HTTP status code, not `request_status`, to detect the error. - `410` — The session has been closed. Use the HTTP status code, not `request_status`, to detect the error. - `415` — The request was rejected because its content type is unsupported. - `422` — Session validation failed. Use the HTTP status code, not `request_status`, to detect the error. - `429` — Rate Limit Exceeded - `500` — Unexpected internal error handled by an API controller. --- [API](https://skmtc.dev/letshum/apis/hum-api.md) · [All operations](https://skmtc.dev/letshum/apis/hum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/letshum/hum-api/revisions/5e36540cb9b0/schema)