Skip to main content
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": "0c970c65-7b01-3fc4-91ee-4ecb31f2acb8",
      "provider_name": "Frontier",
      "provider_icon": null,
      "provider_logo": "https://api.letshum.com/logo.png",
      "telephone": "+18332981433",
      "url": "https://provider.example.com/register",
      "security_token": "fUdh4KG2XQDZarZvPZwSR_YRLPp5eFbD7QUTu7l-53HJ0T3nU2fjaesdOp1O2wUAO9",
      "buyflow_type": "direct",
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 2999
      },
      "button_label": "frontier.com",
      "provider_promo": {
        "promo_text": "",
        "promo_logo_url": ""
      },
      "url_promo": {
        "promo_text": "",
        "promo_logo_url": ""
      },
      "offerings": [
        {
          "technology": "Fiber",
          "max_download_speed": 5000,
          "max_upload_speed": 5000
        }
      ],
      "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"
                },
                "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"
                },
                "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": "XqCmeTVgYXrbWrZFZEymkD",
    "session_status": "open",
    "responded_at": "2025-05-23T17:14:41.903Z",
    "hum_data_set": "25041808"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using API tokens. Include the token in the Authorization header as: Authorization: Bearer <token>

Obtain tokens through your Hum API account dashboard or contact support@letshum.com for access.

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.

​
street1
string
required

The street address of the service location.

Required string length: 1 - 100
Example:

"29090 Tiffany Drive E"

​
street2
string

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

Required string length: 1 - 50
Example:

"A2"

​
city
string

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

Required string length: 1 - 50
Example:

"Southfield"

​
state
enum<string>

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"

​
zip
string

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

​
latitude
number<float>

The latitude of the service address.

Example:

42.501721339274

​
longitude
number<float>

The longitude of the service address.

Example:

-83.286263465881

​
campaign_id
string

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

Required string length: 1 - 100
Example:

"1iYyMxsnTy87tFOvukTi7V"

Response

Successful session creation.

​
message
string
required

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

​
request_status
enum<string>
required

A status code summarizing the outcome of this response.

  • ok: Request was successful
  • warning: Request was processed but with some issues
  • error: Request failed
Available options:
ok,
warning,
error
Example:

"ok"

​
data
object[]
required
​
meta
object
required

Metadata about the session. Can be used to track the status of the session, time since creation, and time since last update.