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

The status of the checkout agent. Pending: The agent has not yet begun processing a checkout for service. 

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.

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.

A unique identifier for the campaign. This is used to track the source of the session in your internal system.

The timestamp when the session was created.

The version of the Hum data set used to generate the response. This version may change as the data set is updated.

A message returned by the API.  Includes a human-readable message about the status of the request.

A status code summarizing the outcome of this response.
- ok: Request was successful
- warning: Request was processed but with some issues
- error: Request failed


The timestamp when the response was generated.

The complete service address as a single string.

The session token provided by the Hum API. Used to connect the response to the session in the client system.

The two-letter state abbreviation of the service location.

The street address of the service location.

The unit, apartment, or suite number of the service location.

The timestamp when the session was last updated.

The ZIP code of the service location in 12345 or 12345-6789 format.

bearerAuth

Incorrect parameters or other validation error

Hum Documentation

Welcome to Hum - Connecting Residents with Internet Services

Introduction

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

## 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"
}
```


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": "29090 TIFFANY DR E, SOUTHFIELD, MI 48034",
  },
  "meta": {
    "agent_status": {
      "geocoding": "matched",
      "internet": "pending"
    }
  }
}
```


Get Session Status

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_id": "0c970c65-7b01-3fc4-91ee-4ecb31f2acb8",
        "provider_name": "Rocket Fiber",
        "telephone": "+18005215881",
        "provider_icon": null,
        "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"
        },
        "promo_text": "",
        "promo_logo": "",
        "offerings": [
          {
            "technology": "Fiber",
            "technology_category": "Terrestrial",
            "max_download_speed": 1000,
            "max_upload_speed": 1000
          }
        ],
        "product_catalog": []
      }
    ]
  },
  "meta": {
    "session_token": "XqCmeTVgYXrbWrZFZEymkD",
    "session_status": "open",
    "responded_at": "2025-05-23T17:14:41.903Z",
    "hum_data_set": "25041808"
  }
}
```

Note: Some providers may return an empty `product_catalog` array.


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"
}
```


Sessions

Service Availability

Health Check

Close Session

Closing Behavior

When to Close

Important Notes

Authorizations

Path Parameters

Response