Building with the Hum API

The Hum API provides a comprehensive set of endpoints for discovering available internet service providers, plans, and pricing at any address in the United States.

Simple Integration Flow

The integration process is straightforward:

Create a session with the service address
Receive immediate provider results in the response
Display available plans to your users

Below is a detailed walkthrough of the integration process:

Get Your API Key Contact your Hum representative to receive your API key. This key is required to authenticate your requests to the Hum API.

Create a Session and Get Immediate Results Start by creating a new session with the service address. The API returns available providers immediately:

curl -X POST https://api.letshum.com/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "street1": "1001 Woodward Ave",
    "street2": "Suite 100",
    "city": "Detroit",
    "state": "MI",
    "zip": "48226"
  }'

Example response with immediate provider data:

{
  "message": "Session created successfully.",
  "request_status": "ok",
  "data": [
    {
      "provider_id": "02c30f10-f3d7-3ae0-9568-96450fac9b1e",
      "provider_name": "Spectrum",
      "provider_icon": null,
      "provider_logo": "https://api.letshum.com/logo/spectrum.png",
      "telephone": "+18332981432",
      "url": "https://api.letshum.com/proxy/provider/spectrum-signup",
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 5000
      },
      "button_label": "spectrum.com",
      "promo_text": "Get started for $50/mo for 12 months",
      "promo_logo": "https://cdn.letshum.com/promo_icons/banknotes.svg",
      "offerings": [
        {
          "technology": "Cable",
          "max_download_speed": 1000,
          "max_upload_speed": 35
        }
      ],
      "product_catalog": [
        {
          "category": "internet",
          "category_name": "Internet Service",
          "category_description": "High-speed internet access plans",
          "products": [
            {
              "id": "8083bfe8-a53f-49eb-b0e8-a77d3e9e7577",
              "sku": "130235-INT-CBL-01",
              "name": "Internet Advantage",
              "category": "internet",
              "category_name": "Internet Service",
              "technology": "cable",
              "position": 1,
              "description": "Boosted Internet for users looking to stream and share content quickly.",
              "download_speed": 100,
              "upload_speed": 20,
              "data_limit": null,
              "channel_count": 0,
              "streaming_apps": [],
              "is_required_to_checkout": true,
              "is_bundle_qualifier": null,
              "required_with_plans": [],
              "included_with_plans": [],
              "initial_term_discount_months": 12,
              "pricing": {
                "monthly_fee": {
                  "amount_cents": 5000,
                  "currency": "USD"
                },
                "extra_data_fee": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "professional_installation_fee": {
                  "amount_cents": 6500,
                  "currency": "USD"
                },
                "self_installation_fee": {
                  "amount_cents": 3000,
                  "currency": "USD"
                },
                "initial_term_discount": {
                  "amount_cents": 2000,
                  "currency": "USD"
                },
                "bundle_discount": {
                  "amount_cents": 1000,
                  "currency": "USD"
                },
                "autopay_discount": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "paperless_billing_discount": {
                  "amount_cents": 0,
                  "currency": "USD"
                }
              }
            },
            {
              "id": "e04cdaa2-feea-4316-a3b5-9104bc2df5a9",
              "sku": "130235-INT-CBL-02",
              "name": "Internet Premier",
              "category": "internet",
              "category_name": "Internet Service",
              "technology": "cable",
              "position": 2,
              "description": "Our most popular Internet speed for remote workers, online students and live streamers.",
              "download_speed": 500,
              "upload_speed": 20,
              "data_limit": null,
              "channel_count": 0,
              "streaming_apps": [],
              "is_required_to_checkout": true,
              "is_bundle_qualifier": null,
              "required_with_plans": [],
              "included_with_plans": [],
              "initial_term_discount_months": 12,
              "pricing": {
                "monthly_fee": {
                  "amount_cents": 8000,
                  "currency": "USD"
                },
                "extra_data_fee": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "professional_installation_fee": {
                  "amount_cents": 6500,
                  "currency": "USD"
                },
                "self_installation_fee": {
                  "amount_cents": 3000,
                  "currency": "USD"
                },
                "initial_term_discount": {
                  "amount_cents": 3000,
                  "currency": "USD"
                },
                "bundle_discount": {
                  "amount_cents": 2000,
                  "currency": "USD"
                },
                "autopay_discount": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "paperless_billing_discount": {
                  "amount_cents": 0,
                  "currency": "USD"
                }
              }
            }
          ]
        },
        {
          "category": "internet_add_on",
          "category_name": "Internet Add-On",
          "category_description": "Additional internet services",
          "products": [
            {
              "id": "36665aaf-c2e4-4cb9-837e-fd2240404b12",
              "sku": "130235-INT-AO-01",
              "name": "WiFi + Modem",
              "category": "internet_add_on",
              "category_name": "Internet Add-On",
              "technology": "not_applicable",
              "position": 1,
              "description": "Complete connectivity for your home WiFi network, with optimized connections and AI-enabled network protection.",
              "download_speed": 0,
              "upload_speed": 0,
              "data_limit": 0,
              "channel_count": 0,
              "streaming_apps": [],
              "is_required_to_checkout": true,
              "is_bundle_qualifier": null,
              "required_with_plans": [],
              "included_with_plans": [],
              "initial_term_discount_months": 24,
              "pricing": {
                "monthly_fee": {
                  "amount_cents": 1000,
                  "currency": "USD"
                },
                "extra_data_fee": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "professional_installation_fee": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "self_installation_fee": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "initial_term_discount": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "bundle_discount": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "autopay_discount": {
                  "amount_cents": 0,
                  "currency": "USD"
                },
                "paperless_billing_discount": {
                  "amount_cents": 0,
                  "currency": "USD"
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "session_token": "XqCmeTVgYXrbWrZFZEymkD",
    "session_status": "open",
    "session_params": {
      "street1": "1001 Woodward Ave",
      "street2": "Suite 100",
      "city": "Detroit",
      "state": "MI",
      "zip": "48226",
      "campaign_id": "summer-2024"
    },
    "service_address": "1001 WOODWARD AVE STE 100, DETROIT, MI 48226",
    "agent_status": {
      "geocoding": "matched",
      "internet": "matched",
      "checkout": "pending"
    },
    "created_at": "2025-05-23T17:14:41.756Z",
    "updated_at": "2025-05-23T17:14:41.756Z",
    "responded_at": "2025-05-23T17:14:41.903Z",
    "hum_data_set": "25041808"
  }
}

Display Available Internet Plans The session creation response includes all available providers and their offerings. You can immediately 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.)

Optional: Retrieve Session Details Later If you need to retrieve session information later, you can use the session token:

curl -X GET https://api.letshum.com/sessions/YOUR_SESSION_TOKEN \
  -H "Authorization: Bearer YOUR_API_KEY"

This endpoint returns session details and processing status, not the provider data:

{
  "message": "Session data retrieved successfully",
  "request_status": "ok",
  "data": {
    "service_address": "1001 WOODWARD AVE STE 100, DETROIT, MI 48226"
  },
  "meta": {
    "session_token": "XqCmeTVgYXrbWrZFZEymkD",
    "session_status": "open",
    "session_params": {
      "street1": "1001 Woodward Ave",
      "street2": "Suite 100",
      "city": "Detroit",
      "state": "MI",
      "zip": "48226",
      "campaign_id": "summer-2024"
    },
    "service_address": "1001 WOODWARD AVE STE 100, DETROIT, MI 48226",
    "agent_status": {
      "geocoding": "matched",
      "internet": "matched",
      "checkout": "pending"
    },
    "created_at": "2025-05-23T17:14:41.756Z",
    "updated_at": "2025-05-23T17:14:41.756Z",
    "responded_at": "2025-05-23T17:14:41.903Z",
    "hum_data_set": "25041808"
  }
}

Note: This endpoint is useful for checking session status and retrieving normalized address information, but the provider data is only returned in the initial session creation response.

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Error Handling

The API uses standard HTTP status codes and returns detailed error messages in the response body. All error responses follow this format:

{
  "message": "Missing session token",
  "request_status": "error",
  "meta": {
    "responded_at": "2024-09-20T23:13:31.179Z",
    "hum_data_set": "v.1005"
  }
}

Common error scenarios include:

400 Bad Request

Missing required fields (street1, city, state, zip)
Invalid address format
Invalid state code
Invalid ZIP code format

401 Unauthorized

Missing or invalid API key
Expired API key
Invalid authentication header format

404 Not Found

Invalid session token
Session not found
Resource not found

406 Not Acceptable

Invalid content type
Missing content type header

410 Gone

Session has been closed
Session has expired

422 Unprocessable Entity

Address validation failed
Invalid parameter values
Business rule violations

429 Too Many Requests

Rate limit exceeded
Too many concurrent sessions

500 Internal Server Error

Server-side processing error
Provider system unavailable
Unexpected system error

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.
Error Handling: Implement robust error handling for common scenarios like invalid addresses, no service availability, or API rate limits. Use the error messages and status codes to provide clear feedback to your users.
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.
Data Caching: Consider caching provider data for frequently requested addresses to improve response times and reduce API calls.
Response Processing: Process the immediate provider data returned in the session creation response to display options to your users without delay.

Example Integration

Here’s a complete example showing how to integrate the Hum API:

async function findInternetProviders(address) {
  try {
    const response = await fetch('https://api.letshum.com/sessions', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(address)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    
    // Providers are immediately available in data.data
    const providers = data.data;
    const sessionToken = data.meta.session_token;
    
    console.log(`Found ${providers.length} providers at ${address.street1}`);
    
    return {
      providers,
      sessionToken,
      serviceAddress: data.meta.service_address
    };
    
  } catch (error) {
    console.error('Error finding providers:', error);
    throw error;
  }
}

// Usage
const address = {
  street1: "1001 Woodward Ave",
  city: "Detroit",
  state: "MI",
  zip: "48226"
};

findInternetProviders(address)
  .then(result => {
    result.providers.forEach(provider => {
      console.log(`${provider.provider_name}: Starting at $${provider.min_plan_price.amount_cents / 100}/mo`);
    });
  })
  .catch(error => {
    console.error('Failed to find providers:', error);
  });

Next Steps

Review our API Reference for detailed endpoint documentation
Try the Widget Integration for a no-code solution

Get Started

Integration

API Integration

Building with the Hum API

Simple Integration Flow

Authentication

Error Handling

400 Bad Request

401 Unauthorized

404 Not Found

406 Not Acceptable

410 Gone

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Best Practices

Example Integration

Next Steps

Get Started

Integration

​Building with the Hum API

​Simple Integration Flow

​Authentication

​Error Handling

​400 Bad Request

​401 Unauthorized

​404 Not Found

​406 Not Acceptable

​410 Gone

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​Best Practices

​Example Integration

​Next Steps

Building with the Hum API

Simple Integration Flow

Authentication

Error Handling

400 Bad Request

401 Unauthorized

404 Not Found

406 Not Acceptable

410 Gone

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

Best Practices

Example Integration

Next Steps