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

# Purchase a Number

> Purchase a phone number from your telephony provider and provision it in your DialNexa workspace for inbound and outbound calling.

<Warning>
  **Legacy endpoint - deprecated.** Unversioned endpoints are scheduled for removal on **July 31, 2026**. Use the [`/v1` version](/docs/api-reference/v1/phone-numbers/buy) for new integrations. This endpoint remains available for existing integrations until then.
</Warning>

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/phone-numbers/search) 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/phone-numbers/search): find a number to purchase.
* [Update Phone Number](/docs/api-reference/phone-numbers/update): assign the number to an inbound agent or set a nickname.
* [Release a Number](/docs/api-reference/v1/phone-numbers/delete): give the number back to the provider's pool.
* [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 /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:
  /organization-phone-numbers/purchase:
    post:
      tags:
        - Organization Phone Numbers
      summary: Purchase a phone number from the specified provider
      description: >-
        **Legacy endpoint - deprecated, scheduled for removal on July 31,
        2026.** Use the `/v1` version for new integrations. 


        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: OrganizationPhoneNumbersController_purchasePhoneNumber
      parameters:
        - name: x-organization-id
          in: header
          description: RSA encrypted organization ID (base64 format)
          required: true
          schema:
            type: string
            example: BASE64_ENCRYPTED_ORG_ID_HERE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchasePhoneNumberRequestDto'
      responses:
        '200':
          description: Phone number purchase initiated and record created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchasePhoneNumberResponseDto'
        '400':
          description: Invalid request or failed to purchase
      deprecated: true
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
    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

````