​
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:

  1. 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.

  2. 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"
  }
}

  3. 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.)

  4. 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