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

# Search Plivo Numbers

> Search available phone numbers from Plivo.

<span data-api-safety-label="read-only"><Badge color="gray" size="sm" shape="pill">Read only</Badge></span>

<Info>
  **Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
</Info>

Searches Plivo's inventory of phone numbers that are available for purchase. This is the discovery step before buying: find a number in the country and pattern you want, then pass it to [Buy Phone Number](/docs/api-reference/v1/phone-numbers/buy).

## When to use this

* **Provisioning a new line**: find an available number in the destination country before purchasing it for inbound or outbound calling.
* **Self-serve number pickers**: let users of your own product browse available numbers before you buy one on their behalf.

If you bring your own number instead of buying one, skip this endpoint and use [Link SIP Trunk](/docs/api-reference/v1/phone-numbers/link-sip-trunk).

## Result

The response lists candidate numbers from Plivo's inventory with their attributes; use the response schema on this page for the exact fields. Availability is live inventory and can change between searching and buying, so purchase promptly after picking a number. See [Errors](/docs/api-reference/errors) for the standard error format.

## Related endpoints

* [Buy Phone Number](/docs/api-reference/v1/phone-numbers/buy): purchase a number found here.
* [List Phone Numbers](/docs/api-reference/v1/phone-numbers/list): the numbers your workspace already owns.
* [Link SIP Trunk](/docs/api-reference/v1/phone-numbers/link-sip-trunk): bring your own number instead.


## OpenAPI

````yaml GET /v1/organization-phone-numbers/plivo-numbers
openapi: 3.0.0
info:
  title: DialNexa API
  description: >-
    Public REST API for the DialNexa voice AI platform. Versioned endpoints are
    under /v1; unversioned endpoints are legacy and deprecated.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: API Keys
  - name: Agent Functions
  - name: Agents V1
  - name: Agents2
  - name: Batch Calls
  - name: Batch Calls V1
  - name: Call Logs
  - name: Calls
  - name: Calls V1
  - name: Campaign Leads
  - name: Campaigns
  - name: External Webhooks
  - name: Knowledge Base
  - name: Knowledge Base V1
  - name: LLMs
  - name: LLMs V1
  - name: Languages
  - name: Languages V1
  - name: Organization Phone Numbers
  - name: Organization Phone Numbers V1
  - name: Phone Number Pricing
  - name: Phone Number Pricing V1
  - name: Transcribers
  - name: Transcribers V1
  - name: User Webhooks
  - name: User Webhooks V1
  - name: V1
  - name: Voices
  - name: Voices V1
  - name: Webcall
  - name: Workflow Leads
  - name: Workflow Leads V1
  - name: Workflows
  - name: Workflows V1
paths:
  /v1/organization-phone-numbers/plivo-numbers:
    get:
      tags:
        - Organization Phone Numbers
        - Organization Phone Numbers V1
        - V1
      summary: Search Plivo Numbers
      description: >-
        Calls the Plivo API with the given country_iso (required) and type
        (optional, e.g. 'tollfree', 'local', 'mobile') and returns the available
        numbers with their capabilities and pricing.
      operationId: OrganizationPhoneNumbersV1Controller_getPlivoNumbers
      parameters:
        - name: country_iso
          required: true
          in: query
          description: ISO country code (e.g., US, GB, CA)
          schema:
            example: US
            type: string
        - name: type
          required: false
          in: query
          description: Type of number (e.g., tollfree, local, mobile)
          schema:
            example: tollfree
            type: string
      responses:
        '200':
          description: Available Plivo numbers returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlivoPhoneNumbersResponseDto'
              examples:
                success:
                  summary: Successful response
                  value:
                    api_id: 9f6d7c
                    objects:
                      - number: '+14155552671'
                        type: local
                        monthly_rental_rate: '0.80'
                        setup_rate: '0.00'
                        voice_enabled: true
                        sms_enabled: true
                        mms_enabled: false
                        country_iso: US
                        number_format: '+14155552671'
                    meta:
                      total_count: 1
        '400':
          description: country_iso is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: country_iso is required
                    error: Bad Request
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    message: API key is missing or invalid
                    error: Unauthorized
        '403':
          description: Forbidden - API key does not have access to this organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 403 Forbidden
                  value:
                    statusCode: 403
                    message: You do not have permission to access this resource
                    error: Forbidden
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
      security:
        - bearer: []
components:
  schemas:
    PlivoPhoneNumbersResponseDto:
      type: object
      properties:
        api_id:
          type: string
          description: API ID for the request
        objects:
          description: List of available phone numbers
          type: array
          items:
            $ref: '#/components/schemas/PlivoPhoneNumberDto'
        meta:
          type: object
          description: Total count of available numbers
      required:
        - api_id
        - objects
        - meta
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: phone_number must be a valid E.164 phone number
        error:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
        - error
    PlivoPhoneNumberDto:
      type: object
      properties:
        number:
          type: string
          description: The phone number
        type:
          type: string
          description: The type of phone number (local, tollfree, etc.)
        monthly_rental_rate:
          type: string
          description: The monthly rental rate for the phone number
        setup_rate:
          type: string
          description: The setup fee for the phone number
        voice_enabled:
          type: boolean
          description: Voice capability of the phone number
        sms_enabled:
          type: boolean
          description: SMS capability of the phone number
        mms_enabled:
          type: boolean
          description: MMS capability of the phone number
        country_iso:
          type: string
          description: Country ISO code
        number_format:
          type: string
          description: The number in international format
      required:
        - number
        - type
        - monthly_rental_rate
        - setup_rate
        - voice_enabled
        - sms_enabled
        - mms_enabled
        - country_iso
        - number_format
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````