---
title: "Buy a phone number"
method: POST
path: "/internal/telephony/phone-numbers/buy"
tags: ["Telephony - Phone Numbers"]
---

# Buy a phone number

`POST /internal/telephony/phone-numbers/buy`

## Request

- Base URL: `https://api.nedzo.ai/v1`
- URL: `https://api.nedzo.ai/v1/internal/telephony/phone-numbers/buy`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nedzo/apis/nedzo-api/docs/internal/telephony/phone-numbers/buy/post.ts> (a function with typed inputs; its response is checked against the schema)

Purchase a phone number.

## Request body

- BuyPhoneNumber
  - `workspaceId` string, uuid, required: Workspace ID
  - `number` string, required: Phone number to purchase
  - `countryDial` string: Country dial code
  - `type` 'inbound_outbound' | 'outbound_only': Phone number type
  - `addressBundleId` string, uuid: Address bundle for compliance
  - `messagingProfileId` string: Messaging profile ID

## Response `201`

Phone number purchased

- PhoneNumber
  - `id` string, uuid, required: Unique identifier
  - `workspaceId` string, uuid, required: Workspace ID
  - `number` string, required: Phone number in E.164 format
  - `countryDial` string, nullable, required: Country dialing code
  - `status` 'pending' | 'active' | 'payment_failed' | 'activation_failed', required: Phone number status
  - `type` 'inbound_outbound' | 'outbound_only', required: Phone number type
  - `engineId` string, nullable, required: Voice engine ID
  - `telephonyId` string, nullable, required: Provider phone number ID
  - `price` number, nullable, required: Monthly price in USD
  - `purchasedAt` string, date-time, nullable, required: Purchase timestamp
  - `renewalAt` string, date-time, nullable, required: Next renewal timestamp
  - `dialsToday` number, required: Dials today
  - `dialsTotal` number, required: Total dials
  - `available` boolean, required: Available for use
  - `deletedAt` string, date-time, nullable, required: Soft delete timestamp
  - `createdAt` string, date-time, required: Creation timestamp
  - `updatedAt` string, date-time, required: Last update timestamp

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden

---

[API](https://skmtc.dev/nedzo/apis/nedzo-api.md) - [All operations](https://skmtc.dev/nedzo/apis/nedzo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nedzo/apis/nedzo-api/revisions/f2607cdb56fa?raw)