Purchase a phone number

curl -X POST 'https://backend.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"
}

Retrying safely

A phone number can only be sold once, so this endpoint cannot charge twice for the same number, with or without a key. The Idempotency-Key header is for recovering a lost response, not for preventing a double sale.

Send a fresh UUID with each purchase. If your request times out, retry with the same key and you get your original order back with replayed: true instead of guessing whether it went through, or 409 in_progress if it is still running.

Reusing a key from a different purchase returns that first order. It is not validated against your new request body, so use a fresh key each time.

Before you can buy

Some regions require the account to be identity-verified first. India is one, and the check is an Aadhaar eKYC, so it completes in minutes. Verification done in the dashboard counts: it is the same gate either way.

Pass the carrier that the search returned, so you buy from the inventory you actually searched. It is always required, and leaving it out is refused with 409 carrier_required listing the carriers for that region.

Verification is per carrier: the account has to be verified on the carrier it is buying from, which KYC status reports per carrier.

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