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

# Search Numbers

> Search for available phone numbers to purchase. Body: country_code (default US), locality, area_code, administrative_area, phone_number_type, page, page_size.



## OpenAPI

````yaml /api-reference/openapi.json post /telephony/numbers/search
openapi: 3.1.0
info:
  title: Truedy API
  description: >-
    Truedy Public API. Authenticate with **Authorization: Bearer
    <your-api-key>** only. Get your API key from the [Truedy
    Dashboard](https://app.truedy.ai). Base URL:
    https://api.truedy.ai/api/public/v1
  version: 1.0.0
servers:
  - url: https://api.truedy.ai/api/public/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Create, configure, test, retrieve, and delete voice agents.
  - name: Calls
    description: >-
      Create and manage outbound calls, recordings, transcripts, and call
      metadata.
  - name: Tools
    description: Create and manage agent tools.
  - name: Knowledge Bases
    description: Legacy Ultravox-backed knowledge bases and sources.
  - name: Knowledge Spaces
    description: >-
      Truedy-native RAG knowledge spaces, sources, ingestion jobs, and
      retrieval.
  - name: Voices
    description: Browse, import, clone, synchronize, preview, and delete voices.
  - name: Telephony
    description: Search, purchase, import, assign, unassign, and release phone numbers.
  - name: Batch Calls
    description: Create and manage outbound batch calling campaigns and their contacts.
  - name: Contacts
    description: Manage contact folders, contacts, imports, and exports.
  - name: Calls
    description: Start browser-based Web Calls with an active agent.
  - name: Widgets
    description: Manage New Frontend widget configurations and embed sessions.
  - name: Agent Templates
    description: Read active agent templates available to the organization.
  - name: Call Explainability
    description: Retrieve redacted structured evidence for a call.
  - name: Webhooks
    description: Manage organization webhook endpoints and delivery history.
  - name: Analytics
    description: Read organization dashboard and conversation intelligence analytics.
  - name: Exports
    description: Export organization calls and campaigns as CSV.
  - name: Workspaces
    description: Create and manage workspaces with an account-scoped master API key.
paths:
  /telephony/numbers/search:
    post:
      tags:
        - Telephony
      summary: Search Numbers
      description: >-
        Search for available phone numbers to purchase. Body: country_code
        (default US), locality, area_code, administrative_area,
        phone_number_type, page, page_size.
      operationId: search_numbers_api_public_v1_telephony_numbers_search_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NumberSearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicNumberSearchResponse'
        '401':
          $ref: '#/components/responses/PublicUnauthorized'
        '403':
          $ref: '#/components/responses/PublicForbidden'
        '422':
          $ref: '#/components/responses/PublicValidationError'
        '429':
          $ref: '#/components/responses/PublicRateLimitExceeded'
        '500':
          $ref: '#/components/responses/PublicInternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    NumberSearchRequest:
      properties:
        country_code:
          type: string
          title: Country Code
          description: ISO country code
          default: US
        locality:
          anyOf:
            - type: string
            - type: 'null'
          title: Locality
          description: City/region to search in
        area_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Area Code
          description: Area code (NDC) to filter by (e.g. 212)
        administrative_area:
          anyOf:
            - type: string
            - type: 'null'
          title: Administrative Area
          description: State or province to filter by
        phone_number_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number Type
          description: 'Telnyx filter: local, toll_free, mobile, national, shared_cost'
        features:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Features
          description: >-
            Telnyx filter: sms, mms, voice, fax, emergency, hd_voice,
            international_sms, local_calling
        best_effort:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Best Effort
          description: Include best-effort results (USA/CANADA)
        reservable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Reservable
          description: Only numbers that can be reserved
        exclude_held_numbers:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Exclude Held Numbers
          description: Exclude numbers on hold for account
        quickship:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Quickship
          description: Exclude numbers needing extra time to activate (+1 toll_free)
        limit:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 1
            - type: 'null'
          title: Limit
          description: Max results per page (overrides page_size when set)
        api_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Api Key
          description: Optional Telnyx API key (uses master if not provided)
        page:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Page
          description: Page number (1-based) for pagination
          default: 1
        page_size:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 1
            - type: 'null'
          title: Page Size
          description: Number of results per page
          default: 20
      type: object
      title: NumberSearchRequest
    PublicNumberSearchResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AvailableNumberResponse'
          type: array
          title: Data
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        pagination:
          $ref: '#/components/schemas/PublicNumberSearchPagination'
      type: object
      required:
        - data
        - meta
        - pagination
      title: PublicNumberSearchResponse
    AvailableNumberResponse:
      properties:
        phone_number:
          type: string
          title: Phone Number
        range:
          anyOf:
            - type: integer
            - type: 'null'
          title: Range
        region_information:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Region Information
        phone_number_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number Type
        features:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Features
        cost_information:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Cost Information
      type: object
      required:
        - phone_number
      title: AvailableNumberResponse
      description: >-
        Available number or block from Telnyx search. cost_information: {
        monthly_cost?, upfront_cost? } (strings).
    ResponseMeta:
      properties:
        request_id:
          type: string
          title: Request Id
          description: Unique request identifier for support and debugging
        ts:
          type: string
          format: date-time
          title: Ts
          description: Server timestamp when the response was generated
      type: object
      required:
        - request_id
        - ts
      title: ResponseMeta
      description: Metadata included in every API response.
    PublicNumberSearchPagination:
      properties:
        page:
          type: integer
          minimum: 1
          title: Page
          description: One-based result page
        page_size:
          type: integer
          minimum: 1
          title: Page Size
          description: Number of results requested per page
        total_results:
          type: integer
          minimum: 0
          title: Total Results
          description: Total available results reported by Telnyx
        total_pages:
          type: integer
          minimum: 0
          title: Total Pages
          description: Total result pages reported or calculated
        has_more:
          type: boolean
          title: Has More
          description: Whether another page is available
      type: object
      required:
        - page
        - page_size
        - total_results
        - total_pages
        - has_more
      title: PublicNumberSearchPagination
    PublicApiErrorResponse:
      type: object
      required:
        - error
        - meta
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
            details:
              description: >-
                Structured, endpoint-specific details. Never rely on
                undocumented provider fields.
              type:
                - object
                - array
                - 'null'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
          description: Request correlation metadata.
      example:
        error:
          code: validation_error
          message: 'Missing required field: name'
          details:
            errors: []
        meta:
          request_id: req_01JEXAMPLE
          ts: '2026-08-21T00:00:00Z'
  responses:
    PublicUnauthorized:
      description: Missing, malformed, expired, inactive, or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicForbidden:
      description: >-
        The API key is valid but the request is not permitted by its
        organization, IP allowlist, or scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicValidationError:
      description: The request is syntactically valid but fails endpoint validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
    PublicRateLimitExceeded:
      description: >-
        The API key or organization exceeded a configured request limit. Retry
        after the response headers/window indicate.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
          description: Seconds until retry is permitted, when available.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Configured request limit.
        X-RateLimit-Remaining:
          schema:
            type: integer
            minimum: 0
          description: Remaining requests in the current window.
        X-RateLimit-Reset:
          schema:
            type: string
            format: date-time
          description: UTC time at which the current window resets.
    PublicInternalError:
      description: Unexpected server failure. Use meta.request_id when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicApiErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Your API key. Send in the Authorization header as: Bearer <your-api-key>'

````