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

Upon session creation, Hum AI agents begin:

Validating and normalizing the address
Geocoding the location
Identifying available service providers
Gathering plan and pricing information

Response Handling

201: Session created successfully, proceed with GET requests to monitor status
422: Invalid address components, check error details
429: Rate limit exceeded, implement exponential backoff

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
The session token is valid for 30 minutes of inactivity
Rate limits apply to all requests

Example Usage

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

The body is of type object.

Response

201

application/json

Successful session creation.

The response is of type object.

Get Session Status

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