​
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 Sign up for a Hum account to receive your API key. You’ll need this key to authenticate your requests.

  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": "1234 Woodward Ave",
    "street2": "Suite 100",
    "city": "Detroit",
    "state": "MI",
    "zip": "48226",
    "sync": ["geocode"]
  }'

    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": null,
      "zip": "48226",
      "campaign_id": "campaignslughere",
      "sync": []
    },
    "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": null,
      "zip": "48226",
      "campaign_id": "campaignslughere",
      "sync": []
    },
    "service_address": {
      "normalized": "1001 WOODWARD AVE, DETROIT, MI, 48226",
      "latitude": 42.332127224438,
      "longitude": -83.047189450703,
      "street_range": "1001-1199",
      "street": "WOODWARD AVE",
      "city": "DETROIT",
      "state": "MI",
      "zip": "48226"
    },
    "agent_status": {
      "geocoding": "pending",
      "internet": "pending",
      "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"
  }
}

    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-sandbox.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-staging.letshum.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsiZGF0YSI6IjhlYTBiOGY2LWNkYTItNDY3MS1iMDA3LTUzYTZlMGMyZGJiYyIsInB1ciI6ImJsb2JfaWQifX0=--c8efd87b3024b386e8d2574e89144c723528b56f/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJwbmciLCJyZXNpemVfdG9fbGltaXQiOls1MDAsNTAwXX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--7adf608a0fa296745940076c6cd1575676529922/130077.svg",
      "url": "https://api-sandbox.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-staging.letshum.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsiZGF0YSI6IjhhYmFhNjZlLTFiODUtNDMzNS04ODU0LTllOTk1MDM3ZjhhZiIsInB1ciI6ImJsb2JfaWQifX0=--cc799c1cf65e16b8e64904a25d73ee2cf78a15cf/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJwbmciLCJyZXNpemVfdG9fbGltaXQiOls1MDAsNTAwXX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--7adf608a0fa296745940076c6cd1575676529922/130317.png",
      "url": "https://api-sandbox.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",
      "sync": []
    },
    "service_address": {
      "normalized": "1001 WOODWARD AVE, DETROIT, MI, 48226",
      "latitude": 42.332127224438,
      "longitude": -83.047189450703,
      "street_range": "1001-1199",
      "street": "WOODWARD AVE",
      "city": "DETROIT",
      "state": "MI",
      "zip": "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": "ok",
  "meta": {
    "responded_at": "2024-09-20T23:13:31.179Z",
    "hum_data_set": "v.1005"
  }
}

Common error scenarios include:

  • Missing or invalid session token
  • Invalid address format
  • No providers found at address
  • Provider data unavailable

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.

  • Rate Limiting: Be mindful of API rate limits and implement appropriate request throttling in your application.

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

​
Next Steps

Was this page helpful?