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

# Buy Phone Number

> Purchase a number through the selected provider.

<span data-api-safety-label="changes-state"><Badge color="yellow" size="sm" shape="pill">Changes state - verify before retry</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>

Purchases a phone number from your telephony provider and provisions it in your DialNexa workspace. The number is immediately available to assign to an agent for handling inbound calls and to use as the outbound caller ID on outbound calls. Numbers are billed monthly, with billing starting on the date of purchase. Use [Search Available Numbers](/docs/api-reference/v1/phone-numbers/search-plivo) first to find a number that fits your needs, then pass the exact E.164 `phone_number` string to this endpoint.

## When to use this

* **New deployments**: provisioning the first number for a region or use case.
* **Capacity expansion**: adding numbers to spread outbound volume across multiple caller IDs and avoid spam flagging.
* **Per-customer or per-brand numbers**: provisioning a dedicated number for a sub-account, partner, or brand.

For India deployments, the recommended path is purchasing through [Plivo](/docs/calls/sip-trunking). For Bring-Your-Own-SIP setups, numbers from your own carrier are connected through SIP trunks rather than purchased here, see [Bring Your Own SIP](/docs/calls/sip-trunking).

## Pre-flight checklist

Before purchasing, confirm:

* The destination country is enabled in **Workspace Settings → Telephony Config**.
* For outbound calling in regulated regions (India, US toll-free, certain EU countries), KYC and verification are complete. See [KYC and outbound readiness](/docs/platform/kyc-and-outbound-readiness).
* The number meets the regulatory requirements for the use case (for example, India 10DLC-equivalent compliance, US toll-free verification).

## Errors

* `400 Bad Request` is returned when the number is no longer available, the country is not enabled on this workspace, or the format is invalid.
* `403 Forbidden` is returned when the workspace has not completed the KYC required for the destination country.
* `409 Conflict` is returned when the number was claimed by another buyer between the search and the purchase.

## Related endpoints

* [Search Available Numbers](/docs/api-reference/v1/phone-numbers/search-plivo): find a number to purchase.
* [List Phone Numbers](/docs/api-reference/v1/phone-numbers/list): confirm the purchased number appears in your workspace.
* [Get Phone Number Details](/docs/api-reference/v1/phone-numbers/get): inspect the purchased number by ID.
* [Delete Phone Number](/docs/api-reference/v1/phone-numbers/delete): remove a number you no longer use.
* [Purchase a Phone Number guide](/docs/calls/phone-numbers): end-to-end provisioning walkthrough.
* [KYC and outbound readiness](/docs/platform/kyc-and-outbound-readiness): verification required before purchasing in regulated regions.


## OpenAPI

````yaml POST /v1/organization-phone-numbers/purchase
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/purchase:
    post:
      tags:
        - Organization Phone Numbers
        - Organization Phone Numbers V1
        - V1
      summary: Purchase Phone Number
      description: >-
        Unified endpoint for purchasing a phone number from either Plivo or
        Twilio. Determines which provider to use from telephonyProviderId
        (1=Plivo, 2=Twilio), calls that provider's API to purchase the number,
        then creates a database record associating it with the organization in a
        single operation. This is the recommended endpoint for purchases, since
        the single-provider endpoints only call the external API without
        creating a database record.
      operationId: OrganizationPhoneNumbersV1Controller_purchasePhoneNumber
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchasePhoneNumberRequestDto'
            examples:
              request:
                summary: Purchase a phone number
                value:
                  phoneNumber: '+14155552671'
                  telephonyProviderId: plivo_123456
                  countryISO: US
      responses:
        '200':
          description: Phone number purchase initiated and record created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchasePhoneNumberResponseDto'
              examples:
                success:
                  summary: Successful response
                  value:
                    phoneNumber: '+1234567890'
                    status: active
                    message: string
                    organizationPhoneNumber:
                      sip_trunk_enabled: false
        '201':
          description: Phone number purchased and registered successfully.
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    phoneNumber: '+14155552671'
                    status: active
                    message: Phone number purchased and registered successfully
                    organizationPhoneNumber:
                      id: phn_abc123
                      phone_number: '+14155552671'
                      provider: plivo
                      status: active
                      country_code: US
                      nickname: US Sales Line
        '400':
          description: Invalid request or failed to purchase
          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:
    PurchasePhoneNumberRequestDto:
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+1234567890'
          description: Phone number to purchase
        telephonyProviderId:
          type: string
          example: plivo_123456
          description: ID of telephony provider (14-char string)
        countryISO:
          type: string
          example: US
          description: Country ISO code (e.g., US, IN)
      required:
        - phoneNumber
        - telephonyProviderId
        - countryISO
    PurchasePhoneNumberResponseDto:
      type: object
      properties:
        phoneNumber:
          type: string
          example: '+1234567890'
          description: Phone number
        status:
          type: string
          enum:
            - active
            - pending
          description: Status of the phone number
        message:
          type: string
          description: Status message
        organizationPhoneNumber:
          description: Organization phone number record
          allOf:
            - $ref: '#/components/schemas/OrganizationPhoneNumber'
      required:
        - phoneNumber
        - status
    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
    OrganizationPhoneNumber:
      type: object
      properties:
        sip_trunk_enabled:
          type: boolean
          default: false
          description: >-
            When true, Speech IO uses SIP trunking (e.g. asterisk) for this
            number.
      required:
        - sip_trunk_enabled
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````