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",
  "city": "Southfield",
  "state": "MI",
  "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",
      "min_plan_price": {
        "currency": "USD",
        "amount_cents": 2999
      },
      "button_label": "frontier.com",
      "promo_text": "",
      "promo_logo": "",
      "offerings": [
        {
          "technology": "Fiber",
          "max_download_speed": 5000,
          "max_upload_speed": 5000
        }
      ],
      "product_catalog": []
    }
  ],
  "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 JWT 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

A JSON object that contains the service address components for the session.

​
street1
string
required

The street address of the service location.

Required string length: 1 - 100
Example:

"29090 Tiffany Drive E"

​
state
enum<string>
required

The two-letter state abbreviation of the service location.

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
Example:

"MI"

​
zip
string
required

The ZIP code of the service location in 12345 or 12345-6789 format.

Example:

48034

​
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 string length: 1 - 50
Example:

"Southfield"

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