> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search numbers to buy

> Local US and Canadian numbers you can buy now, each with its monthly price. `within_free_allowance` is true when your plan covers it, and then the price is 0.



## OpenAPI

````yaml /api-reference/openapi.json get /phone_numbers/available
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Public REST API for Brilo. Authenticate by sending your API key as a Bearer
    token in the `Authorization` header.
  title: Brilo API
  version: '2025-03-02'
servers:
  - description: Production
    url: https://api.brilo.ai/v1
security: []
tags: []
paths:
  /phone_numbers/available:
    get:
      tags:
        - Agents (public)
      summary: Search numbers to buy
      description: >-
        Local US and Canadian numbers you can buy now, each with its monthly
        price. `within_free_allowance` is true when your plan covers it, and
        then the price is 0.
      operationId: searchAvailablePhoneNumbers
      parameters:
        - description: Two-letter country code. US and CA are sold.
          in: query
          name: country
          required: false
          schema:
            default: US
            description: Two-letter country code. US and CA are sold.
            maxLength: 2
            minLength: 2
            type: string
        - description: Only numbers in this area code, for example 512.
          in: query
          name: area_code
          required: false
          schema:
            description: Only numbers in this area code, for example 512.
            pattern: ^\d{3}$
            type: string
        - description: How many numbers to return, at most 30.
          in: query
          name: limit
          required: false
          schema:
            default: 10
            description: How many numbers to return, at most 30.
            maximum: 30
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  data:
                    items:
                      additionalProperties: false
                      properties:
                        country:
                          type: string
                        currency:
                          type: string
                        locality:
                          nullable: true
                          type: string
                        monthly_price:
                          description: >-
                            What the number costs each month. 0 inside your plan
                            allowance.
                          type: number
                        phone_number:
                          type: string
                        region:
                          nullable: true
                          type: string
                        within_free_allowance:
                          type: boolean
                      required:
                        - phone_number
                        - country
                        - locality
                        - region
                        - monthly_price
                        - currency
                        - within_free_allowance
                      type: object
                    type: array
                required:
                  - data
                type: object
          description: ''
        '400':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  details:
                    additionalProperties: {}
                    type: object
                  error_code:
                    type: string
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        error_code:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                      required:
                        - field
                        - error_code
                        - message
                      type: object
                    type: array
                  hint:
                    type: string
                  message:
                    type: string
                  next_action:
                    additionalProperties: false
                    properties:
                      body:
                        additionalProperties: {}
                        type: object
                      method:
                        type: string
                      path:
                        type: string
                      tool:
                        type: string
                    required:
                      - tool
                      - method
                      - path
                    type: object
                  status:
                    maximum: 9007199254740991
                    minimum: -9007199254740991
                    type: integer
                required:
                  - status
                  - error_code
                  - message
                type: object
          description: validation_failed, country_not_supported, toll_free_not_supported
        '502':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  details:
                    additionalProperties: {}
                    type: object
                  error_code:
                    type: string
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        error_code:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                      required:
                        - field
                        - error_code
                        - message
                      type: object
                    type: array
                  hint:
                    type: string
                  message:
                    type: string
                  next_action:
                    additionalProperties: false
                    properties:
                      body:
                        additionalProperties: {}
                        type: object
                      method:
                        type: string
                      path:
                        type: string
                      tool:
                        type: string
                    required:
                      - tool
                      - method
                      - path
                    type: object
                  status:
                    maximum: 9007199254740991
                    minimum: -9007199254740991
                    type: integer
                required:
                  - status
                  - error_code
                  - message
                type: object
          description: 'carrier_unavailable: the number search failed; try again'
        '503':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  details:
                    additionalProperties: {}
                    type: object
                  error_code:
                    type: string
                  errors:
                    items:
                      additionalProperties: false
                      properties:
                        error_code:
                          type: string
                        field:
                          type: string
                        message:
                          type: string
                      required:
                        - field
                        - error_code
                        - message
                      type: object
                    type: array
                  hint:
                    type: string
                  message:
                    type: string
                  next_action:
                    additionalProperties: false
                    properties:
                      body:
                        additionalProperties: {}
                        type: object
                      method:
                        type: string
                      path:
                        type: string
                      tool:
                        type: string
                    required:
                      - tool
                      - method
                      - path
                    type: object
                  status:
                    maximum: 9007199254740991
                    minimum: -9007199254740991
                    type: integer
                required:
                  - status
                  - error_code
                  - message
                type: object
          description: billing_unavailable
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: Enter your API key (Bearer token)
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.