​
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. With a single API call, you can retrieve all available internet options for any address and immediately display them to your users.
The Hum API returns provider data immediately in the session creation response - no polling or additional requests required.

​
Integration Overview

Integrating with Hum is a simple three-step process:
  1. Authenticate with your API key
  2. Create a session with the service address
  3. Display results from the immediate response

​
Quick Start Guide

1

Get Your API Key

Contact your Hum representative to receive your API key. This key authenticates all requests to the Hum API.
Never expose your API key in client-side code or commit it to version control. Always use environment variables or secure configuration management.
2

Create a Session and Get Immediate Results

Make a POST request to create a session with the service address. The API returns all available providers immediately in the response.
cURL
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"
  }'
Success Response
{
  "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"
  }
}
Verify the response includes request_status: "ok" and provider data in the data array.
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.)
Process the provider data immediately from the session creation response - no additional API calls needed.

​
Optional: Retrieve Session Details Later

If you need to retrieve session information later, you can use the session token:
cURL
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:
Session Details Response
   {
     "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"
  }
}
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 consistent format:
Error Response Format
{
  "message": "Missing session token",
  "request_status": "error",
  "meta": {
    "responded_at": "2024-09-20T23:13:31.179Z",
    "hum_data_set": "v.1005"
  }
}
Always check the request_status field in the response. A value of "error" indicates the request failed.

​
Common Error Scenarios

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.
Use address validation services before sending requests to minimize errors and improve match rates.

Error Handling

Implement robust error handling for common scenarios like invalid addresses, no service availability, or API rate limits.
Always provide clear feedback to users when errors occur, using the error messages and status codes from the API response.

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.
Session tokens are valid for retrieving session metadata but don’t provide access to provider data after the initial response.

Performance Optimization

Consider caching provider data for frequently requested addresses to improve response times and reduce API calls.
Process the immediate provider data returned in the session creation response to display options without delay.

​
Example Integration

Here’s a complete example showing how to integrate the Hum API in different programming languages: 
async function findInternetProviders(address) {
  try {
    const response = await fetch('https://api.letshum.com/sessions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.HUM_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

API Reference

Explore detailed endpoint documentation, parameter specifications, and response schemas.

Widget Integration

Try our no-code widget solution for quick integration without custom development.