> ## Documentation Index > Fetch the complete documentation index at: https://docs.letshum.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```json { "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" } } ``` ## OpenAPI ````yaml /swagger.yaml get /sessions/{token} openapi: 3.0.1 info: title: Hum API version: 1.7.0 description: > The Hum API provides a comprehensive solution for discovering and comparing Internet service providers (ISPs) at specific addresses. By leveraging AI-powered agents, the API normalizes addresses, identifies available providers, and returns detailed information about service plans, pricing, and technology options. This makes it an ideal solution for businesses and applications that need to help users find and compare Internet service options in their area. The API provides endpoints for creating and managing sessions, as well as verifying the connection to the API. Each session represents a service address lookup and its provider results. ## API Versioning This API uses semantic versioning. The current version is v1.6.0. For breaking changes, the major version will be incremented. ## Rate Limiting API requests are protected by a global limit of 100 requests per second per client IP. Analytics endpoints have an additional limit of 60 requests per minute per client IP. When a limit is exceeded, the API returns HTTP 429 with a `Retry-After: 60` header. No other rate-limit headers are sent. ## Authentication All endpoints require Bearer token authentication. Tokens must be included in the Authorization header. ## Error Handling Callers should send `Accept: application/json`. Errors handled by API controllers use a common JSON envelope with `message`, `request_status`, and `request_id`; validation errors may also include `errors`. The API emits 400, 401, 403, 404, 406, 410, 418, 422, 429, 500, and 503 statuses. Use the HTTP status code, not `request_status`, for control flow. The `request_id` is a best-effort support reference persisted with the API log. Request logging deliberately cannot break the request, so a logging failure can leave no matching row. Include the request timestamp when reporting an error so support can bound the lookup by date. Exceptions raised before an API controller handles the request, including unmatched routes and some middleware failures, may use Rails' `PublicExceptions` shape instead of the common envelope. `Accept: application/json` guarantees JSON for those responses; a wildcard or missing `Accept` header may receive HTML. One controller-level exception deliberately has a different body: when address validation is temporarily unavailable during session creation, HTTP 503 returns `{ "address_validation_unavailable": true }` and a `Retry-After` header. termsOfService: https://www.letshum.com/terms-of-service contact: name: Hum API Support url: https://docs.letshum.com email: support@letshum.com license: name: Proprietary url: https://www.letshum.com/terms-of-service servers: - url: https://api-sandbox.letshum.com description: Sandbox environment - url: https://api.letshum.com description: Production environment security: [] paths: /sessions/{token}: parameters: - name: token in: path required: true schema: $ref: '#/components/schemas/session_token' description: The session token identifying the specific session get: tags: - Sessions summary: Get Session Status description: > 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 ```json { "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" } } ``` operationId: getSession responses: '200': description: Session data retrieved successfully headers: session_token: $ref: '#/components/headers/session_token' content: application/json: schema: type: object properties: message: $ref: '#/components/schemas/message' request_status: $ref: '#/components/schemas/request_status' qualify_status: $ref: '#/components/schemas/qualify_status' data: $ref: '#/components/schemas/session_token_data' meta: $ref: '#/components/schemas/meta' required: - message - request_status - data - meta '400': $ref: '#/components/responses/400_bad_request' '401': $ref: '#/components/responses/401_unauthorized' '410': $ref: '#/components/responses/410_gone' '415': $ref: '#/components/responses/415_unsupported_media_type' '422': $ref: '#/components/responses/422_unprocessable' '429': $ref: '#/components/responses/429_rate_limit' '500': $ref: '#/components/responses/500_internal_error' security: - bearerAuth: [] components: schemas: session_token: type: string example: XqCmeTVgYXrbWrZFZEymkD description: >- The session token provided by the Hum API. Used to connect the response to the session in the client system. message: type: string example: What happened in the most recent request. description: >- A message returned by the API. Includes a human-readable message about the status of the request. request_status: type: string enum: - ok - warning - error example: ok description: > 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: type: string enum: - available - no_service - pending - failed - retry_later example: available description: > 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. session_token_data: type: object properties: session_token: $ref: '#/components/schemas/session_token' required: - session_token description: >- Session response data. The formatted service address and normalized address components are returned in `meta`. meta: type: object properties: session_token: $ref: '#/components/schemas/session_token' session_status: $ref: '#/components/schemas/session_status' agent_status: $ref: '#/components/schemas/agent_status' session_params: $ref: '#/components/schemas/normalized_session_params' service_address: $ref: '#/components/schemas/service_address' mdu: type: boolean example: false description: Whether the normalized service address is a multi-dwelling unit. created_at: $ref: '#/components/schemas/created_at' updated_at: $ref: '#/components/schemas/updated_at' responded_at: $ref: '#/components/schemas/responded_at' hum_data_set: $ref: '#/components/schemas/hum_data_set' required: - session_token - session_status - session_params - service_address - mdu - agent_status - created_at - updated_at - responded_at - hum_data_set description: >- Session metadata, including normalized input values, formatted service address, session status, and the Hum data set used for the response. session_status: type: string enum: - open - closed example: open description: The status of the session. agent_status: type: object properties: geocoding: type: string enum: - pending - matched - multiple - failed example: matched description: >- The status of the geocoding agent. Pending: The agent has not yet processed the address. Matched: The agent has found a single match for the address. Multiple: The agent has found multiple matches for the address. Failed: The agent was unable to match the address. internet: type: string enum: - pending - matched - failed example: matched description: >- The status of the Internet service availability agent. Pending: The agent has not yet processed the address. Matched: The agent has found Internet service providers for the address. Failed: The agent was unable to find Internet service providers for the address. checkout: type: string enum: - pending example: pending description: >- The status of the checkout agent. Pending: The agent has not yet begun processing a checkout for service. normalized_session_params: type: object description: >- Address and campaign values after normalization. Coordinate values are serialized as strings in response metadata. properties: street1: type: string example: 29090 Tiffany Dr E street2: type: string nullable: true example: null city: type: string example: Southfield state: type: string example: MI zip: type: string example: '48034' latitude: type: string nullable: true example: '42.50189' longitude: type: string nullable: true example: '-83.29528' campaign_id: type: string nullable: true example: null required: - street1 - street2 - city - state - zip - latitude - longitude - campaign_id service_address: type: string example: 1420 Washington Blvd, Detroit, MI 48201 description: The complete service address as a single string. created_at: allOf: - $ref: '#/components/schemas/timestamp' - description: The timestamp when the session was created. updated_at: allOf: - $ref: '#/components/schemas/timestamp' - description: The timestamp when the session was last updated. responded_at: allOf: - $ref: '#/components/schemas/timestamp' - description: The timestamp when the response was generated. hum_data_set: type: string pattern: ^\d+$ example: '25041808' description: >- The version of the Hum data set used to generate the response. This version may change as the data set is updated. error_envelope: type: object properties: message: $ref: '#/components/schemas/message' request_status: type: string enum: - warning - error description: >- Informational severity only; use the HTTP status code for control flow. request_id: $ref: '#/components/schemas/request_id' errors: $ref: '#/components/schemas/errors' required: - message - request_status - request_id timestamp: type: string format: date-time example: '2024-09-20T23:13:31.179Z' description: A timestamp in ISO 8601 format. request_id: type: string example: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 description: > Best-effort support reference for the request. Include the approximate request timestamp when reporting an error. A request logging failure can leave no matching API log row. errors: type: object description: >- Validation errors for session creation (e.g. missing/invalid address combination, street1, state, or zip). properties: base: type: array items: type: string example: >- Provide either (street1 and zip), (street1, city, and state), or (street1, city, and zip) street1: type: array items: type: string example: can't be blank city: type: array items: type: string example: can't be blank state: type: array items: type: string example: must be a valid state or US territory/commonwealth zip: type: array items: type: string example: must be in the form 12345 or 12345-1234 headers: session_token: description: >- The session token provided by the Hum API. Used to connect the response to the session in the client system. required: true schema: type: string example: XqCmeTVgYXrbWrZFZEymkD Retry-After: description: Number of seconds to wait before retrying the request. schema: type: integer example: 60 required: true responses: 400_bad_request: description: >- Bad request. This includes an invalid session token. Use the HTTP status code, not `request_status`, to detect the error. content: application/json: schema: $ref: '#/components/schemas/error_envelope' examples: invalid_parameters: summary: Invalid session parameters value: message: Invalid parameters sent to session. request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 invalid_session_token: summary: Invalid session token value: message: Invalid session token. request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 401_unauthorized: description: >- Unauthorized. Use the HTTP status code, not `request_status`, to detect the error. content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: Unauthorized access request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 410_gone: description: >- The session has been closed. Use the HTTP status code, not `request_status`, to detect the error. content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: Session is closed. Please open a new session. request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 415_unsupported_media_type: description: The request was rejected because its content type is unsupported. content: application/json: schema: type: object properties: error: type: string example: Request rejected message: type: string example: The request was rejected due to security concerns status: type: integer enum: - 415 example: 415 required: - error - message - status 422_unprocessable: description: >- Session validation failed. Use the HTTP status code, not `request_status`, to detect the error. content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: Session could not be created. request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 errors: base: - >- Provide either (street1 and zip), (street1, city, and state), or (street1, city, and zip) 429_rate_limit: description: Rate Limit Exceeded headers: Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: Rate limit exceeded. Please try again later. request_status: warning request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 500_internal_error: description: Unexpected internal error handled by an API controller. content: application/json: schema: $ref: '#/components/schemas/error_envelope' example: message: Internal server error request_status: error request_id: 3f1c3c07-785d-4c59-97dd-25cb38f670d7 securitySchemes: bearerAuth: type: http scheme: bearer description: > Bearer token authentication using API tokens. Include the token in the Authorization header as: `Authorization: Bearer ` Obtain tokens from your Hum representative or contact support@letshum.com. There is no self-serve API key dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.