​
Understanding Hum’s Core Components

The Hum API platform is built around several key concepts that work together to provide you with a seamless experience for discovering and comparing internet service providers.
This guide covers the fundamental concepts you need to understand before integrating with the Hum API. Each concept builds upon the previous ones.

​
Intelligent Agents

Hum’s intelligent agents act as digital assistants that interact with ISP systems on your behalf. These agents streamline the traditionally complex process of checking service availability and gathering accurate plan information for you.

​
How Agents Work

When you create a session, our agents operate through sophisticated automation:
  • Launch secure, isolated virtual browsers for each provider interaction
  • Navigate provider websites and systems in real-time
  • Input your address and service information accurately
  • Extract and validate service availability data
  • Gather current plans, pricing, and promotional offers
  • Handle complex scenarios and variations across different ISP platforms
  • Process results immediately and return them with your session creation
Agents run in isolated environments to ensure your data security and prevent any interference between concurrent requests.

​
Agent Capabilities

Each agent is designed to:
  • Understand and follow provider-specific workflows
  • Handle dynamic website changes and updates
  • Process both structured and unstructured data
  • Validate results for accuracy
  • Retry operations when necessary
  • Adapt to different regional variations in provider systems
  • Deliver immediate availability responses upon address validation
You can verify agent performance by checking the response time and completeness of provider data in your session results.

​
Real-time Processing

Agents work efficiently to ensure you receive accurate data:
  • Multiple agents run concurrently to deliver fast results
  • The system immediately processes and normalizes results
  • Hum validates data against known patterns and rules
  • The platform detects and handles anomalies appropriately
  • You receive service availability immediately with session creation
Concurrent agent processing means you typically receive comprehensive results within 3-5 seconds of creating a session.

​
Sessions

A session represents a single address lookup transaction in the Hum API. When you create a session, it:
  • Provides immediate provider results upon creation
  • Has a unique session token for your future reference
  • Expires after 30 minutes to ensure data accuracy
  • Can be explicitly closed when you no longer need it
  • Returns complete provider and plan information instantly
Sessions expire after 30 minutes to ensure you always receive the most current pricing and availability data.
This session-based approach ensures you receive:
  • Immediate provider discovery results
  • Accurate address validation and
  • Secure and efficient API interactions
  • Complete provider and plan data in one request
Verify your session is active by checking the session token in your API responses. Expired sessions will return a 401 error.

​
Session Flow

​
Address Validation

Hum’s address validation system ensures you receive accurate location data by:
  • Normalizing your addresses to a standard format
  • Geocoding addresses to the
  • Validating address components for accuracy
  • Providing you with detailed address information including:
    • Normalized street address
    • Latitude and longitude coordinates
    • Street range information
    • City, state, and ZIP code
Address validation occurs automatically when you create a session. Invalid addresses will return an error with suggested corrections.

​
Provider Discovery

The provider discovery process delivers comprehensive results by:
  • Identifying all available ISPs at your specified address instantly
  • Retrieving current plan information and pricing for you
  • Validating service availability in real-time
  • Providing you with detailed provider information including:
    • Provider name and contact details
    • Available technologies (DSL, Cable, Fiber, etc.)
    • Plan speeds and pricing
    • Installation options
You can verify discovery completeness by checking that each provider includes technology type, speed tiers, and current pricing in the response.

​
Data Accuracy

Hum maintains high data accuracy to ensure you receive reliable information through:
  • Real-time validation with provider systems
  • Regular updates to provider information directly from the FCC and Internet Service Provider coverage maps
  • Coordination with the FCC and Internet Service Providers with the US Census Bureau to build a hyper-accurate coverage database
  • Address-level service validation down to precise latitude and longitude coordinates
Data accuracy is maintained through continuous validation processes that run 24/7, ensuring you always receive the most current information available.
You can verify data freshness by checking the last_updated timestamp in your API responses, which indicates when the provider data was last validated.