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. Usequalify_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:- Authenticate with your API key
- Create a session with the service address
- 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 tohttps://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.)
Handle Qualification Status
The optionalqualify_status field distinguishes a completed lookup from one that is not ready yet:
The answer is ready:
available: providers were found and are returned indata.no_service: no providers serve this address.datais[]. You can act on this now, but Hum re-checks periodically, so re-validate it if you store it long term.
pending: the lookup has not finished.datais[].retry_later: a transient upstream problem.datais[].
failed: the lookup errored for this address.datais[].
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 withpending 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
data object contains only the session token:
Session Details Response
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 withDELETE /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: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
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.
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
400 Bad Request
400 Bad Request
Common causes:
- Missing session parameters
- Unpermitted session parameters
- Invalid session token
415 Unsupported Media Type
415 Unsupported Media Type
Common causes:
- Unsupported or incorrect request content type
Content-Type: application/json.422 Unprocessable Entity - Validation Failed
422 Unprocessable Entity - Validation Failed
Common causes:Resolution: Use the
- Missing a valid address combination:
street1+zip,street1+city+state, orstreet1+city+zip - Invalid address, state, or ZIP format
Example
errors object to correct the address fields before retrying.429 Too Many Requests - Rate Limiting
429 Too Many Requests - Rate Limiting
Common causes:
- Rate limit exceeded
Retry-After header before retrying.500 Internal Server Error - Server Issues
500 Internal Server Error - Server Issues
Common causes:
- Unexpected server-side failure
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.
Error Handling
Implement robust error handling for common scenarios like invalid addresses, no service availability, or API rate limits.
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.
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.
