---
title: "Buy a virtual number from the platform pool"
method: POST
path: "/buy-number/"
tags: ["Numbers"]
---

# Buy a virtual number from the platform pool

`POST /buy-number/`

## Request

- Base URL: `http://api.smsfusion.com.au`
- URL: `http://api.smsfusion.com.au/buy-number/`
- Auth: one of:
  - API key in query parameter `key`
  - HTTP basic

Leases an available pool number to your account, charges your pre-pay balance and starts the recurring renewal. The optional callback URL receives billing lifecycle events as form POSTs. Payloads: event=purchased carries msisdn, price (decimal string), duration (month|year), nextcharge (YYYY-MM-DD), sent on this purchase; event=renewed carries msisdn, price, nextcharge, sent after each successful renewal charge; event=renewal_failed carries msisdn, price, sent when the wallet cannot cover a renewal - top up promptly to keep the number; event=cancelled carries msisdn, sent when the number is cancelled from either /cancel-number/ or the web Numbers page

## Query parameters

- `key` string, required

## Response `200`

Number purchased and charged

- object
  - `success` boolean
  - `msisdn` string
  - `price` string: Decimal string, e.g. 9.95
  - `duration` string
  - `nextcharge` string
  - `callback` boolean

## Other responses

- `400`: BAD_REQUEST - invalid duration or callback URL
- `401`: Authentication failed or required field 'num' empty
- `404`: NOT_FOUND - number is no longer available
- `405`: Method not allowed - POST only
- `429`: OVER_LIMIT - insufficient funds to purchase number

---

[API](https://skmtc.dev/smsfusion/apis/sms-fusion-api.md) · [All operations](https://skmtc.dev/smsfusion/apis/sms-fusion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smsfusion/apis/sms-fusion-api/revisions/a88b2793a6e9?raw)