Skip to content
DashboardGet API key

Search available phone numbers

View .md
GET

Search for available phone numbers to purchase by country and type.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Query parameters

  • countryCodestringrequired

    Two-letter ISO country code.

    Limitsmin length 2 · max length 2
  • typestring

    Type of phone number to search for.

    One oflocalnationaltollFreemobile
  • containsstring

    Search for numbers containing this string: digits, or letters for vanity numbers. Spaces, dashes, dots and parentheses are ignored, so 1-800 searches 1800.

    Limitsmax length 20
  • capabilitiesstring

    Comma-separated capabilities the number must have: sms, voice, mms. Numbers missing any of them are dropped.

  • limitinteger

    Maximum number of results to return.

    Default10
    Limitsmax 50

Responses

200List of available phone numbers. An empty `items` means the country is served but nothing matched these filters, including a number type the country does not sell (retry with another `type`) and a `contains` pattern no number matches.
  • itemsobject[]required
    6 properties
    • phoneNumberstringrequired
    • friendlyNamestring
    • localitystring
    • regionstring
    • capabilitiesobjectrequired
      3 properties
      • smsboolean
      • voiceboolean
      • mmsboolean
    • pricingobjectrequired
      3 properties
      • monthlyPricenumber

        Monthly price in USD.

      • upfrontPricenumber

        One-time purchase price in USD.

      • isFreeEligibleboolean

        Whether this account can claim this number as the one its paid plan includes: a US or Canadian number (a +1 number) costing $20 a month or less. It depends on the account as well as the number: false on Free, and once the benefit has been claimed, which is once per account and never again, not even after the number is released.

400Invalid query parameters, or `country_restricted`: phone numbers in this country are not sold self-service and need a minimum commitment. The message names who to contact. A `contains` pattern the inventory refused is answered `invalid_request` with `details.field` set to `contains`; one that only matched nothing is a `200` with empty `items`.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404`country_unavailable`: we do not currently stock numbers in this country. Distinct from an empty `items` array, which means the country is served but nothing matched your filters — retry with another `type`.
  • codestringrequired
  • messagestringrequired
  • detailsobject
502The number inventory could not be reached, or refused a search it should accept. Retry; do not treat this as no stock.
  • codestringrequired
  • messagestringrequired
  • detailsobject