Buy a number over the API

Search the OmniDimension number shop, buy a number, and release it when you are done.

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, 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.

Status	Meaning
`409 carrier_required`	The request did not name a carrier. The body lists the ones this region has.
`404 unknown_carrier`	The region has no carrier by that name. The body lists the ones it does have.
`403 feature_disabled`	Phone number access is switched off for that account.
`409 kyc_incomplete`	The region needs identity verification and it is not finished.
`409 number_unavailable`	Someone claimed the number first. Search again and pick another.
`409 in_progress`	A purchase for this number, or under this key, is still running.
`402 insufficient_balance`	The wallet cannot cover the rental. Nothing was 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.

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.