Search available phone numbers
Search the OmniDimension number shop for phone numbers available to buy in a region. Price and validity are flat per region, so every result shows the same monthly_rental_usd and validity_days, and that is the exact amount a purchase will charge.
regionstring · enumrequiredRegion to search in. IN and US both serve numbers. Which regions answer is configuration, so a region with no carrier enabled returns 404 not_available rather than an empty list.
carrierstringrequiredWhich carrier's stock to search: carriers in a region do not sell the same numbers. Always required, even where a region holds one, and omitting it returns 409 carrier_required naming that region's carriers and what each one stocks.
patternstringDigits or prefix to match within the number.
pageintegerPage of results to return.
limitintegerResults per page.
user_idintegerReseller accounts only: the client to act on. Omit it to act on your own account.
curl -X GET 'https://backend.omnidim.io/api/v1/phone_number/search?region=IN&carrier=carrier-1&pattern=555&page=1&limit=20' \ -H 'Authorization: Bearer YOUR_API_KEY'
{ "success": true, "region": "IN", "carrier": "carrier-1", "carrier_label": "Carrier 1", "numbers": [ { "phone_number": "+918000000001", "monthly_rental_usd": 5.06, "validity_days": 30, "region": "IN", "kyc_required": true } ], "total": 1, "page": 1, "limit": 20, "total_pages": 1 }
Authorization
BearerAuth Bearer token authentication. Obtain your API key from the OmniDimension dashboard.
In: header
Query Parameters
Region to search in. IN and US both serve numbers. Which
regions answer is configuration, so a region with no carrier
enabled returns 404 not_available rather than an empty list.
"IN" | "US"Which carrier's stock to search: carriers in a region do not sell
the same numbers. Always required, even where a region holds one,
and omitting it returns 409 carrier_required naming that
region's carriers and what each one stocks.
Digits or prefix to match within the number.
Page of results to return.
11 <= valueResults per page.
201 <= value <= 150Reseller accounts only: the client to act on. Omit it to act on your own account.
Response body
application/jsonResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
Which carrier do I search?
The one whose stock you want, because carriers do not sell the same numbers.
carrier is always required.
| Region | carrier | Stocks |
|---|---|---|
IN | carrier-1 | Landline numbers, city codes 11, 12 and 80 |
IN | carrier-2-new | Mobile numbers, 94 and 79 series |
US | carrier-us | US local numbers, by area code |
You do not have to hard-code that table. Call without a carrier and the
409 carrier_required response lists the carriers for that region with what
each one stocks, which is how an integration discovers a carrier we add later
without a release of its own.
The response names the carrier its results came from, and that is the carrier a purchase has to pass. Verification is per carrier too, so a client must be verified on the carrier it is buying from: see KYC status.
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.
Next step: purchase a number, or read the flow end to end in Buy a number over the API.
List phone numbers
Retrieve the phone numbers on your account, whether you bought them from the OmniDimension number shop or imported your own.
Purchase a phone number
Buy a phone number from the OmniDimension number shop. The monthly rental comes out of your wallet and the number is added to your account, ready to attach to an agent.