Purchase a phone number

A number can only be sold once, so this endpoint cannot double-sell, with or without a key. The Idempotency-Key header is for recovering a lost response: send a fresh UUID with each purchase, and if a request times out, retry with the same key to get your original order back with replayed: true, or 409 in_progress while it is still running.

Some regions require the account to be identity verified first, and the check is per carrier. Pass the carrier the search returned, so you buy from the inventory you actually searched. Verification done in the dashboard counts: it is the same gate either way.

The whole flow is in Buy a number over the API.

curl -X POST 'https://omnidim.io/api/v1/phone_number/purchase' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "region": "IN",
  "carrier": "carrier-1",
  "phone_number": "+918000000001"
}'

{
  "success": false,
  "replayed": false,
  "order_id": 0,
  "phone_number": "string",
  "amount": 0,
  "new_balance": 0,
  "status": "completed"
}