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

​
Example Integration Path

The integration process follows these key steps:

  • Create a session with the service address
  • Poll the session status until both geocoding and internet agents are matched
  • Retrieve available internet plans for the address
  • Display 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 Start by creating a new session with the service address:

    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:

    {
  "message": "Session created successfully.",
  "request_status": "ok",
  "data": {
    "session_token": "tCCDr74LjVPByvGAomPD9wBa"
  },
  "meta": {
    "session_token": "tCCDr74LjVPByvGAomPD9wBa",
    "session_status": "open",
    "session_params": {
      "street1": "1001 Woodward Ave",
      "street2": "Suite 300",
      "city": "Detroit",
      "state": "MI",
      "zip": "48226",
      "campaign_id": "summer-2024"
    },
    "service_address": null,
    "agent_status": {
      "geocoding": "pending",
      "internet": "pending",
      "checkout": "pending"
    },
    "created_at": "2025-04-02T16:56:04.876Z",
    "updated_at": "2025-04-02T16:56:04.876Z",
    "responded_at": "2025-04-02T16:56:04.899Z",
    "hum_data_set": "v.1006"
  }
}

  3. Monitor Session Status Use the session token from the response to check the status of your request:

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

    Example response:

    {
  "message": "Session agents have successfully matched the service address. Please proceed.",
  "request_status": "ok",
  "data": {
    "session_token": "tCCDr74LjVPByvGAomPD9wBa"
  },
  "meta": {
    "session_token": "tCCDr74LjVPByvGAomPD9wBa",
    "session_status": "open",
    "session_params": {
      "street1": "1001 Woodward Ave",
      "street2": "Suite 300",
      "city": "Detroit",
      "state": "MI",
      "zip": "48226",
      "campaign_id": "summer-2024"
    },
    "service_address": "1001 WOODWARD AVE, DETROIT, MI, 48226",
    "agent_status": {
      "geocoding": "matched",
      "internet": "matched",
      "checkout": "pending"
    },
    "created_at": "2025-04-02T16:56:04.876Z",
    "updated_at": "2025-04-02T16:56:05.236Z",
    "responded_at": "2025-04-02T16:57:28.992Z",
    "hum_data_set": "v.1006"
  }
}

  4. Awaiting Agent Responses The API will return available ISPs and their plans for the provided address as the session completes processing. The response includes an agent_status in the meta field that shows the progress of different processing steps:

    "meta": {
  "agent_status": {
    "geocoding": "matched",
    "internet": "matched",
    "checkout": "pending"
  }
}

    Agent status values:

    • geocoding:
      • pending: Address validation in progress
      • matched: Single address match found
      • multiple: Multiple possible matches found
      • failed: Unable to validate address
    • internet:
      • pending: Provider search in progress
      • matched: Providers found
      • failed: No providers found
    • checkout:
      • pending: Ready for checkout process

    Continue polling the session status endpoint every few seconds until both the geocoding and internet agents show “matched” status. The geocoding agent typically completes first, validating and normalizing the address. The internet agent then processes available providers and plans. Once both agents show “matched”, the response will include the complete data for the address.

  5. Display Available Internet Plans Once both agents show “matched” status, you can retrieve the available internet plans for the address. The response will include detailed information about each provider and their available plans, including:

    • Provider name and details
    • Available plans with speeds and pricing
    • Installation options and fees
    • Contract terms and conditions
    curl -X GET https://api.letshum.com/sessions/YOUR_SESSION_TOKEN/services/internet \
  -H "Authorization: Bearer YOUR_API_KEY"

    Example response:

    {
  "message": "Service coverage for 1001 WOODWARD AVE, DETROIT, MI, 48226",
  "request_status": "ok",
  "data": [
    {
      "provider_name": "AT&T",
      "telephone": "+18332981429",
      "provider_logo": "http://harmony.letshum.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsiZGF0YSI6IjhlYTBiOGY2LWNkYTItNDY3MS1iMDA3LTUzYTZlMGMyZGJiYyIsInB1ciI6ImJsb2JfaWQifX0=--c8efd87b3024b386e8d2574e89144c723528b56f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJwbmciLCJyZXNpemVfdG9fbGltaXQiOls1MDAsNTAwXX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--7adf608a0fa296745940076c6cd1575676529922/130077.svg",
      "url": "https://api.letshum.com/proxy/provider/fUdh4KG2XQDZarZvPZwSR_YRNvBpU1Lu9CsU0p1X4HrH6T26MFvPZetcNJMfzRMAId8bwPGCixRDbUEWtgq4Qv28gbIRcFDDAmVEu-_9_zO0x6W5Of6Attez3PBXhUc-fAXdhmpbDlpwMEo=",
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 5500
      },
      "button_label": "View plans on att.com",
      "offerings": [
        {
          "technology": "DSL",
          "technology_category": "Terrestrial",
          "technology_code": null,
          "max_download_speed": 10,
          "max_upload_speed": 1
        }
      ]
    },
    {
      "provider_name": "Xfinity",
      "telephone": "+18332981431",
      "provider_logo": "http://harmony.letshum.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsiZGF0YSI6IjhhYmFhNjZlLTFiODUtNDMzNS04ODU0LTllOTk1MDM3ZjhhZiIsInB1ciI6ImJsb2JfaWQifX0=--cc799c1cf65e16b8e64904a25d73ee2cf78a15cf/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJwbmciLCJyZXNpemVfdG9fbGltaXQiOls1MDAsNTAwXX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--7adf608a0fa296745940076c6cd1575676529922/130317.png",
      "url": "https://api.letshum.com/proxy/provider/fUdh4KG2XQDZarZvPZwSR_YRI8ZVfybN2jYnnqI2-ETo2R3tNUvEUOwKNJMfzRMAId8bwPGCixRDbUEWtgq4Qv28gbIRcFDDAmVEu-_9_zO0x6W5Of6Attez3PBXhUc-fAXdhmpbDlpwMEo=",
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 3000
      },
      "button_label": "View plans on xfinity.com",
      "offerings": [
        {
          "technology": "Cable",
          "technology_category": "Terrestrial",
          "technology_code": null,
          "max_download_speed": 2000,
          "max_upload_speed": 200
        }
      ]
    }
  ],
  "meta": {
    "session_token": "tCCDr74LjVPByvGAomPD9wBa",
    "session_status": "open",
    "session_params": {
      "street1": "1001 Woodward Ave",
      "street2": "Suite 300",
      "city": "Detroit",
      "state": null,
      "zip": "48226",
      "campaign_id": "campaignslughere"
    },
    "service_address": "1001 WOODWARD AVE, DETROIT, MI, 48226",
    "agent_status": {
      "geocoding": "matched",
      "internet": "matched",
      "checkout": "pending"
    },
    "created_at": "2025-04-02T16:56:04.876Z",
    "updated_at": "2025-04-02T16:56:05.236Z",
    "responded_at": "2025-04-02T17:03:21.652Z",
    "hum_data_set": "v.1006"
  }
}

​
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: While Hum validates and geocodes addresses to the Census block level, providing accurate address data upfront ensures 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 are required for all subsequent API calls.

  • Data Caching: Consider caching provider data for frequently requested addresses to improve response times and reduce API calls.

​
Next Steps

Was this page helpful?