---
title: "Create New Session"
method: POST
path: "/sessions"
tags: ["Sessions"]
---

# Create New Session

`POST /sessions`

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
1. Submit service address components
2. Receive a session token
3. Use session token in the URL path for subsequent requests

## Processing
During session creation, Hum:
- Validates and normalizes the address
- Geocodes the location
- Identifies available service providers
- Gathers plan and pricing information

## Response Handling
- 201: Session created successfully with available provider results in `data`
- 422: Invalid address components, check error details
- 429: Rate limit exceeded; retry after the delay in `Retry-After`
- 503: Address validation is temporarily unavailable; retry after the delay in `Retry-After`

## 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
- Sessions remain open until they are closed with DELETE
- Rate limits apply to all requests

## Example Usage
Provide address using one of: **(street1 and zip)**, **(street1, city, and state)**, or **(street1, city, and zip)**. State is optional when zip is present.
```json
POST /sessions
{
  "street1": "29090 Tiffany Drive E",
  "zip": "48034"
}
```
Or with city and state, or street+city+zip (no state):
```json
POST /sessions
{
  "street1": "29090 Tiffany Drive E",
  "city": "Southfield",
  "state": "MI",
  "zip": "48034"
}
```

## Request body

- SessionParams — 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.
  - `street2` string — The unit, apartment, or suite number of the service location.
  - `city` string — The city of the service location. Required when using the (street1, city, state) combination; optional when providing street1 and zip.
  - `state` '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' — The two-letter state abbreviation. Required when using the (street1, city, state) combination; optional when providing street1 and zip.
  - `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.
  - `latitude` number, float — The latitude of the service address.
  - `longitude` number, float — The longitude of the service address.
  - `campaign_id` string — A unique identifier for the campaign. This is used to track the source of the session in your internal system.

## Response `201`

Successful session creation.

- object
  - `message` string, 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.
  - `data` ProviderOffering[], required
    - `provider_id` string, required — FCC provider identifier
    - `provider_name` string, required — The name of the Internet service provider.
    - `telephone` string, nullable, required — The telephone number associated with the record.
    - `provider_icon` string, uri, nullable, required — URL for the provider icon image
    - `provider_logo` string, uri, nullable, required — The logo of the service provider.
    - `url` string, uri, required — URL for accessing the provider website through Hum's tracking system
    - `button_label` string, required — The text to display on the provider's call-to-action button
    - `min_plan_price` Money, required
      - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
      - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
    - `provider_promo` object, nullable, required — Provider-level promotional information
      - `promo_text` string, nullable — Promotional text from the provider
      - `promo_logo` string, nullable — Promotional logo identifier
      - `promo_logo_url` string, uri, nullable — URL for the promotional icon image
    - `url_promo` object, nullable, required — URL/buyflow-specific promotional information
      - `promo_text` string, nullable — Promotional text specific to this URL/technology
      - `promo_logo` string, nullable — Promotional logo identifier
      - `promo_logo_url` string, uri, nullable — URL for the promotional icon image
    - `offerings` object[], required
      - `technology` 'Fiber' | 'Cable' | 'DSL' | 'Satellite' | 'Wireless' | 'Other', required — The technology used to deliver the service.
      - `max_download_speed` integer, required — The advertised maximum download speed in Mbps.
      - `max_upload_speed` integer, required — The advertised maximum upload speed in Mbps.
    - `product_catalog` object[], required — Array of product categories, each containing detailed product offerings from this provider
      - `category` 'internet' | 'internet_add_on' | 'mobile' | 'television' | 'television_add_on' | 'telephone', required — Category identifier
      - `category_name` string, required — Human-readable category name
      - `category_description` string, required — Description of the category
      - `products` object[], required
        - `id` string, uuid, required — Unique product identifier
        - `sku` string, required — Product SKU
        - `name` string, required — Product name
        - `category` string, required — Product category
        - `category_name` string, required — Human-readable category name
        - `technology` 'cable' | 'fiber' | 'dsl' | 'satellite' | 'wireless' | 'not_applicable', required — Technology used for this product
        - `position` integer, required — Display position within category
        - `select_type` 'radio' | 'checkbox', required — How this product should be displayed in UI
        - `description` string, required — Product description
        - `download_speed` string, nullable, required — Download speed in Mbps. Single value (e.g., '400') or hyphen-delimited range (e.g., '50-100')
        - `upload_speed` string, nullable, required — Upload speed in Mbps. Single value (e.g., '169') or hyphen-delimited range (e.g., '10-25')
        - `data_limit` string, required — Data limit display - either GB amount (e.g., "50 GB") or "Unlimited"
        - `channel_count` integer, required — Number of TV channels (for TV products)
        - `streaming_apps` string[], required — Included streaming apps
        - `is_required_to_checkout` boolean, required — Whether this product is required for checkout
        - `is_contract_required` boolean, required — Whether a contract is required for this product
        - `is_modem_router_included` boolean, required — Whether modem/router is included with this product
        - `is_bundle_qualifier` boolean, nullable, required — Whether this product qualifies for bundle discounts
        - `bundle_discounts` object, required — Bundle discount information
        - `is_local_checkout` boolean, required — Whether checkout is available locally
        - `required_with_plans` string[], required — Plans that this product is required with
        - `included_with_plans` string[], required — Plans that include this product
        - `only_available_with_plans` string[], required — Plans that this product is only available with
        - `initial_term_discount_months` integer, required — Number of months for initial term discount
        - `second_term_discount_months` integer, nullable, required — Number of months for second term discount
        - `hum_rank` integer, nullable, required — Hum rank score for this product (0-100, higher is better)
        - `max_quantity` integer, required — Maximum quantity allowed for this product
        - `product_promo` object, required — Product-level promotional information
          - `promo_text` string, nullable — Promotional text for this product
          - `promo_logo_url` string, uri, nullable — URL for the promotional icon image
        - `info` string, required — Additional product information
        - `pricing` object, required — Detailed pricing breakdown for this product
          - `extra_data_fee` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `professional_installation_fee` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `self_installation_fee` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `activation_fee` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `initial_term_discount` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `second_term_discount` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `third_term_discount` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `autopay_discount` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `paperless_billing_discount` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `combined_autopay_paperless_discount` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `net_monthly_price` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
          - `gross_monthly_fee` Money, required
            - `amount_cents` integer, required — The price amount in whole cents. For example, $49.99 would be 4999.
            - `currency` string, required — The currency used for the price. USD, for example, would be US Dollars. CDN would be Canadian Dollars.
  - `meta` Meta, required — Session metadata, including normalized input values, formatted service address, session status, and the Hum data set used for the response.
    - `session_token` string, required — The session token provided by the Hum API. Used to connect the response to the session in the client system.
    - `session_status` 'open' | 'closed', required — The status of the session.
    - `agent_status` AgentStatus, required
      - `geocoding` 'pending' | 'matched' | 'multiple' | 'failed' — 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` 'pending' | 'matched' | 'failed' — 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` 'pending' — The status of the checkout agent. Pending: The agent has not yet begun processing a checkout for service.
    - `session_params` NormalizedSessionParams, required — Address and campaign values after normalization. Coordinate values are serialized as strings in response metadata.
      - `street1` string, required
      - `street2` string, nullable, required
      - `city` string, required
      - `state` string, required
      - `zip` string, required
      - `latitude` string, nullable, required
      - `longitude` string, nullable, required
      - `campaign_id` string, nullable, required
    - `service_address` string, required — The complete service address as a single string.
    - `mdu` boolean, required — Whether the normalized service address is a multi-dwelling unit.
    - `created_at` string, date-time, required — The timestamp when the session was created.
    - `updated_at` string, date-time, required — The timestamp when the session was last updated.
    - `responded_at` string, date-time, required — The timestamp when the response was generated.
    - `hum_data_set` string, required — The version of the Hum data set used to generate the response. This version may change as the data set is updated.

## Other responses

- `400` — Bad request. This includes an invalid session token. Use the HTTP status code, not `request_status`, to detect the error.
- `401` — Unauthorized. Use the HTTP status code, not `request_status`, to detect the error.
- `415` — The request was rejected because its content type is unsupported.
- `422` — Session validation failed. Use the HTTP status code, not `request_status`, to detect the error.
- `429` — Rate Limit Exceeded
- `500` — Unexpected internal error handled by an API controller.
- `503` — Address validation is temporarily unavailable. This deliberate exception to the common error envelope preserves its body and `Retry-After` header.

---

[API](https://skmtc.dev/letshum/apis/hum-api.md) · [All operations](https://skmtc.dev/letshum/apis/hum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/letshum/hum-api/revisions/5e36540cb9b0/schema)