Buy a number over the API

Everything the OmniDimension number shop does in the dashboard, you can do from your own code: search what is available in a region, buy a number, list what you hold, stop one renewing, and release one you no longer need.

Search what is available

GET /api/v1/phone_number/search?region=IN&carrier=carrier-1

carrier is required, because a region can hold more than one and they do not stock the same numbers. Call without it and the 409 carrier_required response lists that region's carriers with what each one stocks, so you can pick one at runtime instead of hard-coding them.

Narrow the results with pattern, and page through with page and limit.

{
  "success": true,
  "region": "IN",
  "carrier": "carrier-1",
  "carrier_label": "Carrier 1",
  "numbers": [
    {
      "phone_number": "+911155590077",
      "monthly_rental_usd": 5.06,
      "validity_days": 30,
      "region": "IN",
      "kyc_required": true
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "total_pages": 3
}

Price and validity are flat per region, so every result carries the same monthly_rental_usd, and that is the exact amount the purchase will charge.

Searching does not reserve anything. A number is claimed only when a purchase starts, so a number you saw a moment ago can be gone by the time you buy it.

Buy one

POST /api/v1/phone_number/purchase
Idempotency-Key: <a fresh UUID>

{ "region": "IN", "carrier": "carrier-1", "phone_number": "+911155590077" }

Buy from the carrier you searched. The search response names the carrier its results came from, and that is the one a purchase has to pass.

The rental comes out of your wallet and the number is added to your account, ready to attach to an agent.

When a purchase is refused

Every refusal that can happen without spending money happens before anything is charged.

Identity verification

Both regions require the account to be verified before it can buy, and verification is per carrier: clearing one carrier of a region does not clear the other. In India the check is an Aadhaar eKYC and completes in minutes. In the US it is a business check that goes to a partner review, and numbers work while that review is pending.

Verification done in the dashboard counts, it is the same gate either way.

List and release

GET  /api/v1/phone_number/list
POST /api/v1/phone_number/release   { "phone_number": "+911155590077" }

Releasing gives the number up and stops its rental, so it is not charged at the next renewal.

Stop a number renewing

POST /api/v1/phone_number/auto_renew   { "phone_number": "+911155590077", "auto_renew": false }

Releasing ends service at once and gives up the days already paid for. Switching auto-renew off instead keeps the number working until the end of its paid period, and it is never charged again:

Send "auto_renew": true before that date and the number renews as normal. Once it is released it cannot be switched back. Every new purchase starts with auto-renew on, including buying back a number you let go.

The same switch is on each number's card in the dashboard.

Reference

Full request and response schemas, with a playground, are in the API reference. For a script that runs search, purchase and attach end to end, see reseller onboarding in the examples repo.