curl --request POST \
--url https://api-sandbox.letshum.com/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"street1": "29090 Tiffany Drive E",
"zip": "48034"
}
'{
"message": "Session created successfully.",
"request_status": "ok",
"data": [
{
"provider_id": "130317",
"provider_name": "Xfinity",
"provider_icon": null,
"provider_logo": "https://cdn.example.com/providers/xfinity-logo.png",
"telephone": "+18332981431",
"url": "https://affiliate.example.com/xfinity?session=SESSION_TOKEN",
"min_plan_price": {
"currency": "USD",
"amount_cents": 4000
},
"button_label": "xfinity.com",
"provider_promo": {},
"url_promo": {},
"offerings": [
{
"technology": "Cable",
"max_download_speed": 1200,
"max_upload_speed": 35
}
],
"product_catalog": [
{
"category": "internet",
"category_name": "Internet Service",
"category_description": "High-speed internet access plans",
"products": [
{
"id": "a5d1cba2-10f8-4469-8296-9b1b02f83516",
"sku": "130317-INT-CBL-02",
"name": "300 Mbps",
"category": "internet",
"category_name": "Internet Service",
"technology": "cable",
"position": 2,
"select_type": "radio",
"description": "Great for everyday working, streaming, and learning. Price guaranteed for 60 months. No contract required.",
"download_speed": "300",
"upload_speed": "100",
"data_limit": "Unlimited",
"channel_count": 0,
"streaming_apps": [],
"is_required_to_checkout": true,
"is_contract_required": false,
"is_modem_router_included": true,
"is_bundle_qualifier": false,
"bundle_discounts": {},
"is_local_checkout": true,
"required_with_plans": [],
"included_with_plans": [],
"only_available_with_plans": [],
"initial_term_discount_months": 60,
"second_term_discount_months": null,
"hum_rank": 69,
"max_quantity": 1,
"product_promo": {},
"info": "5-year price lock guarantee",
"pricing": {
"extra_data_fee": {
"amount_cents": 0,
"currency": "USD"
},
"professional_installation_fee": {
"amount_cents": 5000,
"currency": "USD"
},
"self_installation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"activation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"initial_term_discount": {
"amount_cents": 1500,
"currency": "USD"
},
"second_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"third_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"autopay_discount": {
"amount_cents": 0,
"currency": "USD"
},
"paperless_billing_discount": {
"amount_cents": 0,
"currency": "USD"
},
"combined_autopay_paperless_discount": {
"amount_cents": 1000,
"currency": "USD"
},
"net_monthly_price": {
"amount_cents": 5500,
"currency": "USD"
},
"gross_monthly_fee": {
"amount_cents": 8000,
"currency": "USD"
}
}
}
]
},
{
"category": "internet_add_on",
"category_name": "Internet Add-On",
"category_description": "Additional internet services",
"products": [
{
"id": "d5ff2d5a-2145-4c5e-95c5-05ed78fc473a",
"sku": "130317-INT-AO-01",
"name": "Xfinity WiFi Gateway (modem + router)",
"category": "internet_add_on",
"category_name": "Internet Add-On",
"technology": "not_applicable",
"position": 1,
"select_type": "radio",
"description": "The most reliable WiFi with our best equipment. Free Advanced Security. Parental controls.",
"download_speed": null,
"upload_speed": null,
"data_limit": "0 GB",
"channel_count": 0,
"streaming_apps": [],
"is_required_to_checkout": false,
"is_contract_required": false,
"is_modem_router_included": false,
"is_bundle_qualifier": false,
"bundle_discounts": {},
"is_local_checkout": true,
"required_with_plans": [],
"included_with_plans": [
"130317-INT-CBL-01",
"130317-INT-CBL-02",
"130317-INT-CBL-03"
],
"only_available_with_plans": [
"130317-INT-CBL-01",
"130317-INT-CBL-02",
"130317-INT-CBL-03"
],
"initial_term_discount_months": 0,
"second_term_discount_months": null,
"hum_rank": null,
"max_quantity": 1,
"product_promo": {},
"info": "",
"pricing": {
"extra_data_fee": {
"amount_cents": 0,
"currency": "USD"
},
"professional_installation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"self_installation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"activation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"initial_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"second_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"third_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"autopay_discount": {
"amount_cents": 0,
"currency": "USD"
},
"paperless_billing_discount": {
"amount_cents": 0,
"currency": "USD"
},
"combined_autopay_paperless_discount": {
"amount_cents": 0,
"currency": "USD"
},
"net_monthly_price": {
"amount_cents": 0,
"currency": "USD"
},
"gross_monthly_fee": {
"amount_cents": 0,
"currency": "USD"
}
}
}
]
}
]
}
],
"meta": {
"session_token": "SESSION_TOKEN_PLACEHOLDER",
"session_status": "open",
"session_params": {
"street1": "29090 Tiffany Dr E",
"street2": "Apt 4B",
"city": "Southfield",
"state": "MI",
"zip": "48034",
"latitude": "42.50189",
"longitude": "-83.29528",
"campaign_id": null
},
"service_address": "29090 Tiffany Dr E Apt 4B, Southfield, MI 48034-4540",
"mdu": true,
"agent_status": {
"geocoding": "matched",
"internet": "matched",
"checkout": "pending"
},
"created_at": "2026-07-13T12:26:15.618-04:00",
"updated_at": "2026-07-13T12:26:15.618-04:00",
"responded_at": "2026-07-13T16:26:16.278Z",
"hum_data_set": "26011015"
}
}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
curl --request POST \
--url https://api-sandbox.letshum.com/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"street1": "29090 Tiffany Drive E",
"zip": "48034"
}
'{
"message": "Session created successfully.",
"request_status": "ok",
"data": [
{
"provider_id": "130317",
"provider_name": "Xfinity",
"provider_icon": null,
"provider_logo": "https://cdn.example.com/providers/xfinity-logo.png",
"telephone": "+18332981431",
"url": "https://affiliate.example.com/xfinity?session=SESSION_TOKEN",
"min_plan_price": {
"currency": "USD",
"amount_cents": 4000
},
"button_label": "xfinity.com",
"provider_promo": {},
"url_promo": {},
"offerings": [
{
"technology": "Cable",
"max_download_speed": 1200,
"max_upload_speed": 35
}
],
"product_catalog": [
{
"category": "internet",
"category_name": "Internet Service",
"category_description": "High-speed internet access plans",
"products": [
{
"id": "a5d1cba2-10f8-4469-8296-9b1b02f83516",
"sku": "130317-INT-CBL-02",
"name": "300 Mbps",
"category": "internet",
"category_name": "Internet Service",
"technology": "cable",
"position": 2,
"select_type": "radio",
"description": "Great for everyday working, streaming, and learning. Price guaranteed for 60 months. No contract required.",
"download_speed": "300",
"upload_speed": "100",
"data_limit": "Unlimited",
"channel_count": 0,
"streaming_apps": [],
"is_required_to_checkout": true,
"is_contract_required": false,
"is_modem_router_included": true,
"is_bundle_qualifier": false,
"bundle_discounts": {},
"is_local_checkout": true,
"required_with_plans": [],
"included_with_plans": [],
"only_available_with_plans": [],
"initial_term_discount_months": 60,
"second_term_discount_months": null,
"hum_rank": 69,
"max_quantity": 1,
"product_promo": {},
"info": "5-year price lock guarantee",
"pricing": {
"extra_data_fee": {
"amount_cents": 0,
"currency": "USD"
},
"professional_installation_fee": {
"amount_cents": 5000,
"currency": "USD"
},
"self_installation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"activation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"initial_term_discount": {
"amount_cents": 1500,
"currency": "USD"
},
"second_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"third_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"autopay_discount": {
"amount_cents": 0,
"currency": "USD"
},
"paperless_billing_discount": {
"amount_cents": 0,
"currency": "USD"
},
"combined_autopay_paperless_discount": {
"amount_cents": 1000,
"currency": "USD"
},
"net_monthly_price": {
"amount_cents": 5500,
"currency": "USD"
},
"gross_monthly_fee": {
"amount_cents": 8000,
"currency": "USD"
}
}
}
]
},
{
"category": "internet_add_on",
"category_name": "Internet Add-On",
"category_description": "Additional internet services",
"products": [
{
"id": "d5ff2d5a-2145-4c5e-95c5-05ed78fc473a",
"sku": "130317-INT-AO-01",
"name": "Xfinity WiFi Gateway (modem + router)",
"category": "internet_add_on",
"category_name": "Internet Add-On",
"technology": "not_applicable",
"position": 1,
"select_type": "radio",
"description": "The most reliable WiFi with our best equipment. Free Advanced Security. Parental controls.",
"download_speed": null,
"upload_speed": null,
"data_limit": "0 GB",
"channel_count": 0,
"streaming_apps": [],
"is_required_to_checkout": false,
"is_contract_required": false,
"is_modem_router_included": false,
"is_bundle_qualifier": false,
"bundle_discounts": {},
"is_local_checkout": true,
"required_with_plans": [],
"included_with_plans": [
"130317-INT-CBL-01",
"130317-INT-CBL-02",
"130317-INT-CBL-03"
],
"only_available_with_plans": [
"130317-INT-CBL-01",
"130317-INT-CBL-02",
"130317-INT-CBL-03"
],
"initial_term_discount_months": 0,
"second_term_discount_months": null,
"hum_rank": null,
"max_quantity": 1,
"product_promo": {},
"info": "",
"pricing": {
"extra_data_fee": {
"amount_cents": 0,
"currency": "USD"
},
"professional_installation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"self_installation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"activation_fee": {
"amount_cents": 0,
"currency": "USD"
},
"initial_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"second_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"third_term_discount": {
"amount_cents": 0,
"currency": "USD"
},
"autopay_discount": {
"amount_cents": 0,
"currency": "USD"
},
"paperless_billing_discount": {
"amount_cents": 0,
"currency": "USD"
},
"combined_autopay_paperless_discount": {
"amount_cents": 0,
"currency": "USD"
},
"net_monthly_price": {
"amount_cents": 0,
"currency": "USD"
},
"gross_monthly_fee": {
"amount_cents": 0,
"currency": "USD"
}
}
}
]
}
]
}
],
"meta": {
"session_token": "SESSION_TOKEN_PLACEHOLDER",
"session_status": "open",
"session_params": {
"street1": "29090 Tiffany Dr E",
"street2": "Apt 4B",
"city": "Southfield",
"state": "MI",
"zip": "48034",
"latitude": "42.50189",
"longitude": "-83.29528",
"campaign_id": null
},
"service_address": "29090 Tiffany Dr E Apt 4B, Southfield, MI 48034-4540",
"mdu": true,
"agent_status": {
"geocoding": "matched",
"internet": "matched",
"checkout": "pending"
},
"created_at": "2026-07-13T12:26:15.618-04:00",
"updated_at": "2026-07-13T12:26:15.618-04:00",
"responded_at": "2026-07-13T16:26:16.278Z",
"hum_data_set": "26011015"
}
}Authorizations
Bearer token authentication using API tokens.
Include the token in the Authorization header as: Authorization: Bearer <token>
Obtain tokens from your Hum representative or contact support@letshum.com. There is no self-serve API key dashboard.
Body
application/json
Service address for the session. Provide one of: street1 and zip; street1, city, and state; or street1, city, and zip. State is optional when zip is present. street2, latitude, longitude, and campaign_id are optional.
Service address. Provide one of: street1 and zip; street1, city, and state; or street1, city, and zip. State is optional when zip is present.
The street address of the service location.
Required string length:
1 - 100Example:
"29090 Tiffany Drive E"
The unit, apartment, or suite number of the service location.
Required string length:
1 - 50Example:
"A2"
The city of the service location. Required when using the (street1, city, state) combination; optional when providing street1 and zip.
Required string length:
1 - 50Example:
"Southfield"
The two-letter state abbreviation. Required when using the (street1, city, state) combination; optional when providing street1 and zip.
Available options:
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 Pattern:
^[A-Z]{2}$Example:
"MI"
The ZIP code in 12345 or 12345-6789 format. Required when using the (street1, zip) combination; optional when providing street1, city, and state.
Pattern:
^\d{5}(-\d{4})?$Example:
48034
The latitude of the service address.
Example:
42.501721339274
The longitude of the service address.
Example:
-83.286263465881
A unique identifier for the campaign. This is used to track the source of the session in your internal system.
Required string length:
1 - 100Example:
"1iYyMxsnTy87tFOvukTi7V"
Response
Successful session creation.
A message returned by the API. Includes a human-readable message about the status of the request.
Example:
"What happened in the most recent request."
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.
Available options:
ok, warning, error Example:
"ok"
Show child attributes
Show child attributes
Session metadata, including normalized input values, formatted service address, session status, and the Hum data set used for the response.
Show child attributes
Show child attributes
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 indata.no_service: No providers serve this address.datais[]. 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.datais[]. Retry by pollingGET /sessions/{token}/services/internet.retry_later: A transient upstream problem.datais[]. Retry by pollingGET /sessions/{token}/services/internet.
Something went wrong:
failed: The lookup errored for this address.datais[].
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.
Available options:
available, no_service, pending, failed, retry_later Example:
"available"
Was this page helpful?