Skip to main content

Building with the Hum API

The Hum API provides endpoints for discovering available internet service providers, plans, and pricing at addresses in the United States. Most address lookups start asynchronously and complete through polling. Results are returned immediately only when the building was looked up recently. Use qualify_status to determine whether to poll or display the results. The partner API provides availability lookup and reporting. Residents place orders through the Hum widget checkout; the partner API does not provide an order-placement endpoint.
Expect qualify_status: "pending" on the first lookup of an address, and plan your integration around polling GET /sessions/{token}/services/internet for the result. If the building was looked up recently, provider data may be available immediately in the session creation response.

Integration Overview

Integrating with Hum is a simple three-step process:
  1. Authenticate with your API key
  2. Create a session with the service address
  3. Check qualify_status, then poll for completion or display an immediate result

Quick Start Guide

Start in Sandbox with the examples below. To go live, switch the base URL to https://api.letshum.com and use your Production key; see Environments and API Keys.
1

Get Your API Key

See Environments and API Keys to request an API key and choose the matching environment.
2

Create a Session and Check Results

Make a POST request to create a session with the service address. Expect to poll for provider results, and check qualify_status to determine whether polling is needed or results are ready immediately.
cURL
Success Response
Branch on qualify_status: expect pending and poll for completion, use data for available, treat only no_service as no service, and also poll for retry_later.
3

Display Available Internet Plans

When qualify_status is available, the response includes all available providers and their offerings. You can display this information to your users:
  • Provider name and contact details
  • Available plans with speeds and pricing
  • Direct links to provider signup pages
  • Technology types (DSL, Cable, Fiber, etc.)
Polling is the expected path for most lookups. When qualify_status is pending or retry_later, poll the Internet service availability endpoint for the result.

Handle Qualification Status

The optional qualify_status field 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_later: a transient upstream problem. data is [].
Something went wrong:
  • failed: the lookup errored for this address. data is [].
A pending lookup finishes as one of three values: available if providers were found, no_service if the lookup completed and found none, or failed if it errored. retry_later arises separately and does not follow from pending. Those three are the states that should end your polling loop. For pending or retry_later, use the session token to poll GET /sessions/{token}/services/internet with a bounded retry. Only no_service means the completed lookup found no service; never interpret data: [] by itself as a no-service result.

Polling duration

Addresses that have not been looked up recently, including most single-family addresses, start with pending and resolve through polling. They commonly take 20 to 30 seconds to resolve, and occasionally longer. While the status is pending or retry_later, poll GET /sessions/{token}/services/internet every 2 seconds. Give up after about 90 seconds of polling. Giving up means the answer is still unknown, not that no service is available. Re-check the address later if the result matters. Only no_service means no service.

Optional: Retrieve Session Details Later

If you need to retrieve session information later, you can use the session token:
cURL
This endpoint returns session details and normalized address metadata. Its data object contains only the session token:
Session Details Response
While the session is open, retrieve its provider offerings again with GET /sessions/{token}/services/internet. See Get Internet Service Availability in the API Reference. For analytics session detail, GET /analytics/sessions/{id} accepts either the session UUID returned by the analytics index or the session token returned when the session was created.

Session Lifecycle

Sessions stay open until you close them with DELETE /sessions/{token}. Close a session when its lookup is finished; see Close Session.

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:
Use authenticated GET /ping as the safest first call before creating a session. It verifies that the selected environment accepts your key; see Environments and API Keys.

Error Handling

The API uses HTTP status codes to indicate success or failure. Standard validation, authentication, and session errors return this format:
Error Response Format
The message describes the result, request_status provides informational severity, and request_id is a support reference for the request. Validation responses may also include an errors object with field-specific details. The request_id is best-effort because request logging failures cannot be allowed to break the request. A logging failure can leave no matching API log row. When reporting an error, quote the request_id and the request timestamp so support can bound the lookup by date.
Use the HTTP status code to determine whether a request succeeded. The request_status field is informational.
Successful session metadata identifies the Hum data set with a numeric string such as "26011015". Responses raised before an API controller handles the request may use a different format, as documented in the API Reference.

Common Error Scenarios

Common causes:
  • Missing session parameters
  • Unpermitted session parameters
  • Invalid session token
Resolution: Verify the request body uses supported session fields and confirm that the session token is correct.
Common causes:
  • Missing or invalid API key
  • Expired API key
  • Invalid authentication header format
Resolution: Verify your API key is correct and properly formatted in the Authorization header.
Common causes:
  • Unsupported or incorrect request content type
Resolution: Send session creation requests with Content-Type: application/json.
Common causes:
  • Missing a valid address combination: street1 + zip, street1 + city + state, or street1 + city + zip
  • Invalid address, state, or ZIP format
Example
Resolution: Use the errors object to correct the address fields before retrying.
When address validation is temporarily unavailable during session creation, this response is an exception to the common error envelope.
Response
Resolution: Respect the Retry-After response header and retry later.
Common causes:
  • Rate limit exceeded
Resolution: Wait for the delay specified by the Retry-After header before retrying.
Common causes:
  • Unexpected server-side failure
Resolution: Retry the request after a brief delay. Contact support if the issue persists.
For detailed error codes and handling, refer to the API Reference documentation.

Best Practices

Address Validation

Provide accurate address data upfront to ensure the best results. Include complete address details including street number, street name, city, state, and ZIP code.
Use address validation services before sending requests to minimize errors and improve match rates.

Error Handling

Implement robust error handling for common scenarios like invalid addresses, no service availability, or API rate limits.
Always provide clear feedback to users when errors occur, using the error messages and status codes from the API response.

Session Management

Store and manage session tokens appropriately. Each session represents a unique address lookup, and tokens can be used to retrieve session details later.

Performance Optimization

Consider caching provider data for frequently requested addresses to improve response times and reduce API calls.
Process provider data from the session creation response when qualify_status is available; poll when it is pending or retry_later.

Example Integration

Here’s a complete example showing how to integrate the Hum API in different programming languages:

Next Steps

API Reference

Explore detailed endpoint documentation, parameter specifications, and response schemas.

Postman Collection

Import ready-made requests for Sandbox or Production.

Widget Integration

Try our no-code widget solution for quick integration without custom development.