> ## 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 FCC Service Providers

> Retrieves a comprehensive list of FCC service providers and their supplemental brands. 
This endpoint provides access to the complete database of Internet service providers 
that are tracked by the FCC and used by Hum for service availability lookups.

## Use Cases
- Building provider selection interfaces
- Validating provider names and IDs
- Understanding provider coverage and scale
- Integration with external systems

## Data Structure
The response includes both primary FCC providers and their supplemental brands:
- **Primary Providers**: Main FCC-registered service providers
- **Supplemental Brands**: Subsidiary brands and service lines under parent providers
- **Total Residential Units**: Coverage metrics for each provider

## Provider Types
- `fcc_provider`: Primary FCC-registered service provider
- `supplemental_brand`: Supplemental brand that inherits coverage from parent provider
- Supplemental brands are grouped immediately after their parent provider

## Response Format
Providers are ordered by total residential units (largest first) with supplemental 
brands immediately following their parent provider in the list.

## Example Response
```json
{
  "providers": [
    {
      "id": "130403",
      "name": "T-Mobile",
      "fcc_name": "T-Mobile USA, Inc.",
      "total_residential_units": 97951103,
      "type": "fcc_provider"
    },
    { 
        "id": "130077",
        "name": "AT&T",
        "fcc_name": "AT&T Inc.",
        "total_residential_units": 80864481,
        "type": "fcc_provider"
    },
    {
        "id": "130317",
        "name": "Xfinity",
        "fcc_name": "Comcast Corporation",
        "total_residential_units": 57287455,
        "type": "fcc_provider"
    },
    {
        "id": "130317-1",
        "name": "Now XFinity",
        "fcc_name": "Comcast Corporation",
        "total_residential_units": 57287455,
        "type": "supplemental_brand"
    },
    {
        "id": "131425",
        "name": "Verizon",
        "fcc_name": "Verizon Communications Inc.",
        "total_residential_units": 50554772,
        "type": "fcc_provider"
    }
  ]
}
```

## Important Notes
- All requests require a valid bearer token
- Response includes both active and inactive providers
- Supplemental brands reference their parent provider's FCC name
- Total residential units represent the parent provider's coverage




## OpenAPI

````yaml /swagger.yaml get /service_providers
openapi: 3.0.1
info:
  title: Hum API
  version: 1.6.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:
  /service_providers:
    get:
      tags:
        - Informational
      summary: Get FCC Service Providers
      description: >
        Retrieves a comprehensive list of FCC service providers and their
        supplemental brands. 

        This endpoint provides access to the complete database of Internet
        service providers 

        that are tracked by the FCC and used by Hum for service availability
        lookups.


        ## Use Cases

        - Building provider selection interfaces

        - Validating provider names and IDs

        - Understanding provider coverage and scale

        - Integration with external systems


        ## Data Structure

        The response includes both primary FCC providers and their supplemental
        brands:

        - **Primary Providers**: Main FCC-registered service providers

        - **Supplemental Brands**: Subsidiary brands and service lines under
        parent providers

        - **Total Residential Units**: Coverage metrics for each provider


        ## Provider Types

        - `fcc_provider`: Primary FCC-registered service provider

        - `supplemental_brand`: Supplemental brand that inherits coverage from
        parent provider

        - Supplemental brands are grouped immediately after their parent
        provider


        ## Response Format

        Providers are ordered by total residential units (largest first) with
        supplemental 

        brands immediately following their parent provider in the list.


        ## Example Response

        ```json

        {
          "providers": [
            {
              "id": "130403",
              "name": "T-Mobile",
              "fcc_name": "T-Mobile USA, Inc.",
              "total_residential_units": 97951103,
              "type": "fcc_provider"
            },
            { 
                "id": "130077",
                "name": "AT&T",
                "fcc_name": "AT&T Inc.",
                "total_residential_units": 80864481,
                "type": "fcc_provider"
            },
            {
                "id": "130317",
                "name": "Xfinity",
                "fcc_name": "Comcast Corporation",
                "total_residential_units": 57287455,
                "type": "fcc_provider"
            },
            {
                "id": "130317-1",
                "name": "Now XFinity",
                "fcc_name": "Comcast Corporation",
                "total_residential_units": 57287455,
                "type": "supplemental_brand"
            },
            {
                "id": "131425",
                "name": "Verizon",
                "fcc_name": "Verizon Communications Inc.",
                "total_residential_units": 50554772,
                "type": "fcc_provider"
            }
          ]
        }

        ```


        ## Important Notes

        - All requests require a valid bearer token

        - Response includes both active and inactive providers

        - Supplemental brands reference their parent provider's FCC name

        - Total residential units represent the parent provider's coverage
      operationId: getServiceProviders
      responses:
        '200':
          description: Service providers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  providers:
                    type: array
                    description: Array of service providers and their supplemental brands
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            Unique provider identifier (FCC provider ID or
                            synthetic ID for brands)
                          example: '12345'
                        name:
                          type: string
                          description: Display name of the provider or brand
                          example: Comcast Cable Communications
                        fcc_name:
                          type: string
                          description: Official FCC registered name of the parent provider
                          example: Comcast Cable Communications, LLC
                        total_residential_units:
                          type: integer
                          description: >-
                            Total number of residential units served by the
                            provider
                          example: 50000000
                        type:
                          type: string
                          enum:
                            - fcc_provider
                            - supplemental_brand
                          description: >-
                            Type of provider - 'fcc_provider' for primary FCC
                            providers, 'supplemental_brand' for supplemental
                            brands
                          example: fcc_provider
                      required:
                        - id
                        - name
                        - fcc_name
                        - total_residential_units
                required:
                  - providers
              examples:
                major_providers:
                  summary: Major Internet Service Providers
                  description: Example response showing major ISPs and their brands
                  value:
                    providers:
                      - id: '12345'
                        name: Comcast Cable Communications
                        fcc_name: Comcast Cable Communications, LLC
                        total_residential_units: 50000000
                        type: fcc_provider
                      - id: 12345-Xfinity
                        name: Xfinity
                        fcc_name: Comcast Cable Communications, LLC
                        total_residential_units: 50000000
                        type: supplemental_brand
                      - id: '67890'
                        name: Charter Communications
                        fcc_name: Charter Communications, Inc.
                        total_residential_units: 30000000
                        type: fcc_provider
                      - id: 67890-Spectrum
                        name: Spectrum
                        fcc_name: Charter Communications, Inc.
                        total_residential_units: 30000000
        '401':
          $ref: '#/components/responses/401_unauthorized'
        '415':
          $ref: '#/components/responses/415_unsupported_media_type'
        '429':
          $ref: '#/components/responses/429_rate_limit'
        '500':
          $ref: '#/components/responses/500_internal_error'
      security:
        - bearerAuth: []
components:
  responses:
    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
    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
    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
  headers:
    Retry-After:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
      example: 60
      required: true
  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.

````