Sessions

Create New Session

Creates a new session for processing a service address. This is typically the first endpoint called when starting a new address lookup flow.

Request Flow

Submit service address components
Receive a session token
Use session token in the URL path for subsequent requests

Processing

During session creation, Hum:

Validates and normalizes the address
Geocodes the location
Identifies available service providers
Gathers plan and pricing information

Response Handling

201: Session created successfully with available provider results in data
422: Invalid address components, check error details
429: Rate limit exceeded; retry after the delay in Retry-After
503: Address validation is temporarily unavailable; retry after the delay in Retry-After

Important Notes

The session token is part of the URL path for all requests after creation
The session token is required for all subsequent requests
Sessions remain open until they are closed with DELETE
Rate limits apply to all requests

Example Usage

Provide address using one of: (street1 and zip), (street1, city, and state), or (street1, city, and zip). State is optional when zip is present.

POST /sessions
{
  "street1": "29090 Tiffany Drive E",
  "zip": "48034"
}

Or with city and state, or street+city+zip (no state):

POST /sessions
{
  "street1": "29090 Tiffany Drive E",
  "city": "Southfield",
  "state": "MI",
  "zip": "48034"
}

post/sessions

Request body

street1string required

The street address of the service location.

street2string

The unit, apartment, or suite number of the service location.

citystring

The city of the service location. Required when using the (street1, city, state) combination; optional when providing street1 and zip.

state'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'PR' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY'

The two-letter state abbreviation. Required when using the (street1, city, state) combination; optional when providing street1 and zip.

zipstring

The ZIP code in 12345 or 12345-6789 format. Required when using the (street1, zip) combination; optional when providing street1, city, and state.

latitudenumber float

The latitude of the service address.

longitudenumber float

The longitude of the service address.

campaign_idstring

A unique identifier for the campaign. This is used to track the source of the session in your internal system.

Example request

{
  "street1": "29090 Tiffany Drive E",
  "street2": "A2",
  "city": "Southfield",
  "state": "MI",
  "latitude": 42.501721339274,
  "longitude": -83.286263465881,
  "campaign_id": "1iYyMxsnTy87tFOvukTi7V"
}

Response

Successful session creation.

messagestring required

A message returned by the API. Includes a human-readable message about the status of the request.

request_status'ok' | 'warning' | 'error' required

An informational summary returned in API response bodies: ok for successful responses, warning for standard request errors, and error for endpoint-specific failures. Integrations must use the HTTP status code, not request_status, to determine whether a request succeeded.

qualify_status'available' | 'no_service' | 'pending' | 'failed' | 'retry_later'

The status of Internet service qualification for the address distinguishes a completed lookup from one that is not ready yet.

The answer is ready:

available: Providers were found and are returned in data.
no_service: No providers serve this address. data is []. You can act on this now, but Hum re-checks periodically, so re-validate it if you store it long term.

The answer is not ready, keep polling:

pending: The lookup has not finished. data is []. Retry by polling GET /sessions/{token}/services/internet.
retry_later: A transient upstream problem. data is []. Retry by polling GET /sessions/{token}/services/internet.

Something went wrong:

failed: The lookup errored for this address. data is [].

A pending lookup finishes as one of three values: available when providers are found, no_service when the lookup completes and finds none, or failed when it errors. retry_later arises separately and does not follow from pending. These three values should end the polling loop.

Example response

{
  "message": "What happened in the most recent request.",
  "request_status": "ok",
  "qualify_status": "available",
  "data": [
    {
      "provider_id": "130317",
      "provider_name": "Rocket Fiber",
      "telephone": "+18332981433",
      "provider_logo": "https://harmony.letshum.com/images/providers/rocketfiber.png",
      "url": "https://provider.example.com/register?utm_source=Hum",
      "button_label": "Get Started",
      "min_plan_price": {
        "amount_cents": 4999,
        "currency": "USD"
      },
      "provider_promo": {
        "promo_text": "$50 off your first month!",
        "promo_logo": "sale-badge",
        "promo_logo_url": "https://cdn.letshum.com/promo_icons/banknotes.svg"
      },
      "url_promo": {
        "promo_text": "Limited time fiber offer!",
        "promo_logo": "fiber-special",
        "promo_logo_url": "https://cdn.letshum.com/promo_icons/fiber-deal.svg"
      },
      "offerings": [
        {
          "technology": "Fiber",
          "max_download_speed": 1000,
          "max_upload_speed": 1000
        }
      ],
      "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,
              "select_type": "radio",
              "description": "Boosted Internet for users looking to stream and share content quickly.",
              "download_speed": "50-100",
              "upload_speed": "10-25",
              "data_limit": "Unlimited",
              "streaming_apps": [
                "Disney+ Basic",
                "ESPN+"
              ],
              "is_required_to_checkout": true,
              "bundle_discounts": {},
              "is_local_checkout": true,
              "required_with_plans": [],
              "included_with_plans": [],
              "only_available_with_plans": [],
              "initial_term_discount_months": 12,
              "hum_rank": 85,
              "max_quantity": 1,
              "product_promo": {},
              "info": "5-year price lock guarantee",
              "pricing": {
                "extra_data_fee": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "professional_installation_fee": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "self_installation_fee": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "activation_fee": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "initial_term_discount": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "second_term_discount": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "third_term_discount": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "autopay_discount": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "paperless_billing_discount": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "combined_autopay_paperless_discount": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "net_monthly_price": {
                  "amount_cents": 4999,
                  "currency": "USD"
                },
                "gross_monthly_fee": {
                  "amount_cents": 4999,
                  "currency": "USD"
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "session_token": "XqCmeTVgYXrbWrZFZEymkD",
    "session_status": "open",
    "agent_status": {
      "geocoding": "matched",
      "internet": "matched",
      "checkout": "pending"
    },
    "session_params": {
      "street1": "29090 Tiffany Dr E",
      "city": "Southfield",
      "state": "MI",
      "zip": "48034",
      "latitude": "42.50189",
      "longitude": "-83.29528"
    },
    "service_address": "1420 Washington Blvd, Detroit, MI 48201",
    "created_at": "2024-09-20T23:13:31.179Z",
    "updated_at": "2024-09-20T23:13:31.179Z",
    "responded_at": "2024-09-20T23:13:31.179Z",
    "hum_data_set": "25041808"
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.