---
title: "Purchase Number"
method: POST
path: "/v1/numbers/purchase"
tags: ["Phone Provisioning", "Phone Provisioning"]
---

# Purchase Number

`POST /v1/numbers/purchase`

## Request

- Base URL: `https://api.call2me.app`
- URL: `https://api.call2me.app/v1/numbers/purchase`
- Auth: HTTP bearer

Purchase a phone number from Telnyx, charge user, bind to their account.

Security rules:
  - User must have made at least one paid top-up (not just signup bonus).
    Trial users cannot spend their bonus on number rentals.
  - Balance must cover upfront charge.
  - Only allowed countries (platform_settings.telnyx_allowed_countries).

## Request body

- PurchaseRequest
  - `phone_number` string, required: E.164 format, e.g., +12125551234
  - `agent_id` string, nullable: Agent to bind (optional)
  - `provider` string, nullable: telnyx | twilio (auto by country if omitted)

## Response `200`

Successful Response

- PurchaseResponse
  - `success` boolean, required
  - `phone_number` string, required
  - `order_id` string, required
  - `monthly_price_usd` number, required
  - `balance_after_usd` number, required
  - `message` string, required

## Other responses

- `422`: Validation Error

---

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