Sign in
Sessions

Get Session Status

Retrieves an open session. Provider results are usually returned by POST /sessions, but when qualify_status is pending or retry_later, poll GET /sessions/{token}/services/internet until the status resolves.

Status Codes

  • 200: Session is open
  • 400: Session token is invalid
  • 410: Session is closed

Response Data

  • data.session_token: The session token only
  • meta.session_params: Normalized address values
  • meta.service_address: Formatted service address
  • meta.agent_status: Agent status values

Important Notes

  • The session token is part of the URL path for all requests after creation
  • Sessions remain open until they are closed with DELETE

Example Response

{
  "message": "Session agents have successfully matched the service address. Please proceed.",
  "request_status": "ok",
  "data": {
    "session_token": "SESSION_TOKEN_PLACEHOLDER"
  },
  "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.900Z",
    "hum_data_set": "26011015"
  }
}
get/sessions/{token}

Response

Session data retrieved successfully

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": {
    "session_token": "XqCmeTVgYXrbWrZFZEymkD"
  },
  "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