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": "US",
  "phone_number": "+15551234567"
}'

{
  "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.

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