---
title: "Buy Phone Numbers"
method: POST
path: "/phone-numbers/buy"
tags: ["phoneNumbers"]
---

# Buy Phone Numbers

`POST /phone-numbers/buy`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/phone-numbers/buy`
- Auth: API key in header `PINNACLE-API-KEY`

Purchase one or more phone numbers found through the [search endpoint](./search). <br>

Billing uses your account credits and the numbers are ready for immediate use.

## Request body

- BuySchema: Purchase one or more available phone numbers that meet your criteria. <br> Each number will be verified for availability before completing the purchase.
  - `numbers` string[], required: List of phone numbers you want to purchase, each in international E.164 format. <br> All specified numbers must be currently available and will be validated for availability before processing the purchase. <br> If any number in the request is unavailable or invalid, no purchases will be made and the request will be voided.

## Response `200`

Successfully purchased the number(s).

- BuyResponse[]
  - `number` string, required: Purchased phone number in E.164 format.
  - `capabilities` BuyResponseCapabilities, required: Enabled communication features for the phone number.
    - `sms` boolean, required: Indicates if SMS messaging is enabled and functional.
    - `mms` boolean, required: Indicates if multimedia messaging (images, videos, files) is enabled and functional.
    - `voice` boolean, required: Indicates if voice calling is enabled and functional.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `402`: Insufficient credits to complete this request. <br> This occurs when your account balance is below the required amount for processing the operation. Please add credits to your account to continue using the service.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)