---
title: "Purchase a phone number"
method: POST
path: "/numbers/phones"
tags: ["Numbers"]
---

# Purchase a phone number

`POST /numbers/phones`

Starts a Mobilerun Phone purchase for the authenticated owner. Accepted requests always return the same asynchronous envelope; poll GET /numbers/phones/{id} for its business state. `purpose` and `country` are mutually exclusive.

## Headers

- `Idempotency-Key` string — Optional request idempotency key.

## Request body

- PublicPhonePurchaseInput
  - `purpose` string — Optional Mobilerun Phone purpose slug from GET /numbers/purposes.
  - `country` string — Optional ISO 3166-1 alpha-2 country code from GET /numbers/countries. Cannot be combined with `purpose`.
  - `billingPreference` 'included' | 'rent' — Prefer a free package seat ('included', default) or force the paid checkout ('rent')

## Response `202`

Number purchase accepted — poll GET /numbers/phones/{id}

- object
  - `data` PurchaseAcceptedResponse, required
    - `numberId` string, uuid, required
    - `state` 'awaiting_payment' | 'provisioning', required
    - `checkoutUrl` string, nullable, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `409` — Purchase in progress
- `422` — Unsupported purpose or country
- `500` — Internal Server Error
- `503` — Purchase unavailable

---

[API](https://skmtc.dev/droidrun/apis/droidrun-cloud.md) · [All operations](https://skmtc.dev/droidrun/apis/droidrun-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/droidrun/droidrun-cloud/revisions/a1453ac769d4/schema)