Skip to content
DashboardGet API key

Search numbers to buy

View .md
GET

Search numbers to buy, by country and type.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Query parameters

  • countryCodestringrequired
    Limitsmin length 2 · max length 2
  • typestring

    Type of phone number. mobile is stocked in countries where no geographic (local) or non-geographic (national) inventory exists, and in several markets it is the only type that can receive SMS.

    One oflocalnationaltollFreemobile
  • containsstring
    Limitsmax length 20
  • capabilitiesstring
  • limitinteger
    Default10
    Limitsmax 50

Responses

200Numbers.
  • 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 number qualifies as the plan-included number: a US or Canadian number (a +1 number) costing $20 a month or less. The benefit is one per account: it is never offered again once claimed, not even after the number is released.

400Invalid query, or `country_restricted`.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring
404`country_unavailable`: no stock in this country.
  • codestringrequired
  • messagestringrequired
  • detailsobject

    Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.

    1 properties
    • errorsobject[]
      3 properties
      • pathobject[]required
      • messagestringrequired
      • codestring