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

# Close Session

> Closes an active session. Sessions remain open until this endpoint is called.

## Closing Behavior
- The response returns the session envelope with `meta.session_status` set to `closed`
- Subsequent operations on the closed session return HTTP 410

## When to Close
- After completing service lookup
- When switching to a different address
- After receiving final results
- When abandoning a search

## Important Notes
- A closed session cannot be reopened
- Create a new session to perform another lookup




## OpenAPI

````yaml /swagger.yaml delete /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.
  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
    delete:
      tags:
        - Sessions
      summary: Close Session
      description: >
        Closes an active session. Sessions remain open until this endpoint is
        called.


        ## Closing Behavior

        - The response returns the session envelope with `meta.session_status`
        set to `closed`

        - Subsequent operations on the closed session return HTTP 410


        ## When to Close

        - After completing service lookup

        - When switching to a different address

        - After receiving final results

        - When abandoning a search


        ## Important Notes

        - A closed session cannot be reopened

        - Create a new session to perform another lookup
      operationId: closeSession
      responses:
        '200':
          description: Session closed successfully
          headers:
            session_token:
              $ref: '#/components/headers/session_token'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Session closed successfully.
                  request_status:
                    $ref: '#/components/schemas/request_status'
                  data:
                    $ref: '#/components/schemas/session_token_data'
                  meta:
                    $ref: '#/components/schemas/meta'
                required:
                  - message
                  - request_status
                  - data
                  - meta
              example:
                message: Session closed successfully.
                request_status: ok
                data:
                  session_token: SESSION_TOKEN_PLACEHOLDER
                meta:
                  session_token: SESSION_TOKEN_PLACEHOLDER
                  session_status: closed
                  session_params:
                    street1: 29090 Tiffany Dr E
                    street2: null
                    city: Southfield
                    state: MI
                    zip: '48034'
                    latitude: '42.50189'
                    longitude: '-83.29528'
                    campaign_id: null
                  service_address: 29090 Tiffany Dr E, Southfield, MI 48034-4540
                  mdu: false
                  agent_status:
                    geocoding: matched
                    internet: matched
                    checkout: pending
                  created_at: '2026-07-13T12:26:15.618-04:00'
                  updated_at: '2026-07-13T12:27:33.031-04:00'
                  responded_at: '2026-07-13T16:27:33.185Z'
                  hum_data_set: '26011015'
        '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.
    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.
    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.
    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.
    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
    timestamp:
      type: string
      format: date-time
      example: '2024-09-20T23:13:31.179Z'
      description: A timestamp in ISO 8601 format.
  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:
            type: object
            properties:
              message:
                type: string
                example: Invalid session token.
              request_status:
                type: string
                enum:
                  - warning
                example: warning
            required:
              - message
              - request_status
          examples:
            invalid_parameters:
              summary: Invalid session parameters
              value:
                message: Invalid parameters sent to session.
                request_status: warning
            invalid_session_token:
              summary: Invalid session token
              value:
                message: Invalid session token.
                request_status: warning
    401_unauthorized:
      description: >-
        Unauthorized. Use the HTTP status code, not `request_status`, to detect
        the error.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized access
              request_status:
                type: string
                enum:
                  - warning
                example: warning
            required:
              - message
              - request_status
    410_gone:
      description: >-
        The session has been closed. Use the HTTP status code, not
        `request_status`, to detect the error.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Session is closed. Please open a new session.
              request_status:
                type: string
                enum:
                  - warning
                example: warning
            required:
              - message
              - request_status
    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:
            type: object
            properties:
              message:
                $ref: '#/components/schemas/message'
              request_status:
                type: string
                enum:
                  - warning
                example: warning
              errors:
                $ref: '#/components/schemas/errors'
            required:
              - message
              - request_status
              - errors
          example:
            message: Session could not be created.
            request_status: warning
            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:
            type: object
            properties:
              error:
                type: string
                example: Too many requests
              message:
                type: string
                example: Rate limit exceeded. Please try again later.
              status:
                type: integer
                enum:
                  - 429
                example: 429
            required:
              - error
              - message
              - status
    500_internal_error:
      description: >-
        Internal Server Error. The response body is not guaranteed to use the
        standard API envelope.
      content:
        application/json:
          schema:
            oneOf:
              - type: object
                properties:
                  status:
                    type: integer
                    example: 500
                  error:
                    type: string
                    example: Internal Server Error
                required:
                  - status
                  - error
              - type: object
                properties:
                  message:
                    type: string
                    example: Internal server error
                required:
                  - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Bearer token authentication using API tokens.

        Include the token in the Authorization header as: `Authorization: Bearer
        <token>`


        Obtain tokens from your Hum representative or contact
        support@letshum.com. There is no self-serve API key dashboard.

````