.mint-block {
    display: block
}
.mint-hidden {
    display: none
}
.mint-rounded-lg {
    border-radius: 0.5rem
}
.mint-shadow-lg {
    --tw-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
    --tw-shadow-colored: 0 10px 15px -3px var(--tw-shadow-color), 0 4px 6px -4px var(--tw-shadow-color);
    box-shadow: var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--tw-shadow)
}
.dark\:mint-block:is(.dark *) {
    display: block
}
.dark\:mint-hidden:is(.dark *) {
    display: none
}

The Hum Platform

What Hum Does

How It Works

Integration Options

Next Steps

Welcome to Hum - Connecting Residents with Internet Services

Introduction

Hum Documentation

Understanding the core concepts of the Hum platform

Key Concepts

Learn how to integrate Hum into your application using our API

API Integration

Learn how to integrate Hum into your website using our widget

Widget Integration

Creates a new session for processing a service address. This is typically the first endpoint called when starting 
a new address lookup flow.

## Request Flow
1. Submit service address components
2. Receive a session token
3. Use session token in the URL path for subsequent requests

## Processing
Upon session creation, Hum AI agents begin:
- Validating and normalizing the address
- Geocoding the location
- Identifying available service providers
- Gathering plan and pricing information

## Synchronous Processing
You can optionally specify certain agents to run synchronously during the request by providing the `sync` parameter:
- Include agent names in an array: `["geocode", "internet"]`
- Available agents: `geocode`, `internet`
- Synchronous requests may take longer to complete but return more complete initial data
- Use this for time-sensitive operations where immediate results are required
- AI agents (ie, plans, pricing, etc) are run asynchronously by default and cannot be run synchronously
- Updates to the plans and pricing components will be available asynchronously after each AI agent completes processing

## Response Handling
- 201: Session created successfully, proceed with GET requests to monitor status
- 422: Invalid address components, check error details
- 429: Rate limit exceeded, implement exponential backoff

## Important Notes
- The session token is part of the URL path for all requests after creation
- The session token is required for all subsequent requests
- The session token is valid for 30 minutes of inactivity
- Rate limits apply to all requests

## Example Usage
```json
POST /sessions
{
  "street1": "29090 Tiffany Drive E",
  "city": "Southfield",
  "state": "MI",
  "zip": "48034",
  "sync": ["geocode"]
}
```


Create New Session

Retrieves the current status of a session, including normalized address data and processing status of various 
Hum AI agents.

## Polling Guidelines
- Initial request: Immediately after session creation
- Subsequent requests: Every 2-3 seconds until agents complete
- Maximum polling duration: 30 seconds
- Implement exponential backoff if status doesn't change

## Status Codes
- 200: Session active and data available
- 202: Session active but still processing
- 410: Session expired or closed

## Response Data
- Normalized address
- Geocoding results
- Agent processing status
- Available services (when ready)

## Important Notes
- The session token is part of the URL path for all requests after creation
- The session token is required for all subsequent requests
- The session token is valid for 30 minutes of inactivity
- Rate limits apply to all requests

## Example Response
```json
{
  "message": "Session data retrieved successfully",
  "request_status": "ok",
  "data": {
    "service_address": {
      "normalized": "29090 TIFFANY DR E, SOUTHFIELD, MI 48034",
      "latitude": 42.501721,
      "longitude": -83.286263
    }
  },
  "meta": {
    "agent_status": {
      "geocoding": "matched",
      "internet": "pending"
    }
  }
}
```


Get Session Status

Updates the service address components for an existing session. Use this endpoint when you need to correct 
address information or modify the search parameters.

## Update Behavior
- Existing session data is preserved where possible
- AI agents re-run with new address data
- Previous results are invalidated
- New session token is issued

## Common Use Cases
- Correcting typos in address
- Adding missing unit numbers
- Switching to a nearby address
- Updating ZIP code

## Important Notes
- Updates reset agent processing
- Previous results may be temporarily available
- Rate limits apply to updates
- Session expiry time is reset

## Example Usage
```json
PUT /sessions/{token}
{
  "street1": "29090 Tiffany Drive E",
  "street2": "Suite 100",
  "city": "Southfield",
  "state": "MI",
  "zip": "48034"
}
```


Update Session Data

Explicitly closes an active session. While sessions automatically expire after inactivity, it's best practice 
to close them when you're done to free up resources.

## Closing Behavior
- All agent processing stops immediately
- Cached results are cleared
- Session token becomes invalid
- Resources are freed

## When to Close
- After completing service lookup
- When switching to a different address
- After receiving final results
- When abandoning a search

## Important Notes
- Cannot be undone
- New session required for same address
- Final results should be saved before closing
- Rate limits still apply


Close Session

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

## Response Timing
- Initial request may return 202 if still processing
- Results typically available within 5-15 seconds
- Implement polling with backoff strategy

## Data Freshness
- Results cached for 24 hours
- Real-time availability checks on checkout
- Pricing updated daily
- Coverage maps updated weekly

## Example Response
```json
{
  "message": "Service coverage for 29090 TIFFANY DR E, SOUTHFIELD, MI 48034",
  "request_status": "ok",
  "data": {
    "internet": [
      {
        "provider_name": "Rocket Fiber",
        "telephone": "800-521-5881",
        "provider_logo": "https://harmony.letshum.com/images/providers/rocketfiber.png",
        "url": "https://provider.example.com/register?utm_source=Hum",
        "button_label": "Get Started",
        "min_plan_price": {
          "amount_cents": 4999,
          "currency": "USD"
        },
        "offerings": [
          {
            "technology": "Fiber",
            "technology_category": "Terrestrial",
            "technology_code": "FTTH",
            "max_download_speed": 1000,
            "max_upload_speed": 1000,
            "tech_logo": "https://harmony.letshum.com/images/technologies/fiber.png"
          }
        ]
      }
    ]
  }
}
```


Get Internet Service Availability

Simple health check endpoint to verify API availability and authentication status. Use this endpoint 
for monitoring and to validate API tokens.

## Use Cases
- Monitoring API health
- Validating API tokens
- Testing CORS configuration
- Checking rate limits

## Response Times
- Expected: < 100ms
- Warning: > 500ms
- Critical: > 1000ms

## Monitoring Guidelines
- Poll every 60 seconds
- Implement circuit breaker pattern
- Track response times
- Monitor error rates

## Example Response
```json
{
  "message": "🎤 We're humming along!",
  "request_status": "ok",
  "data": {},
  "timestamp": "2024-03-20T23:13:31.179Z"
}
```


Get Started

​The Hum Platform

​What Hum Does

​How It Works

​Integration Options

​Next Steps

The Hum Platform

What Hum Does

How It Works

Integration Options

Next Steps