Sign in
Phone Numbers

Search available numbers

Search the provider's inventory for numbers available to purchase in a country (default US). Optional filters narrow the results. The country must be offerable (see GET /v1/phone-numbers/countries). Voice capability is always required; pass sms=true to only see numbers that can also text (SMS support is per-number, not per-country). Numbers a purchase would refuse are left out, and any result's phoneNumber can be bought exactly by passing it to POST /v1/phone-numbers/purchase.

Works without an API key. Keyless calls get up to 12 results with the middle digits masked (maskedNumber), each with a claimId and a claimUrl: a signup link that lands a person on the dashboard's confirm step with that number picked, so an agent can search for a user and hand them one link. Keyless calls are rate limited per IP and results are cached for a few minutes. With an API key you get full numbers and no claim fields.

get/v1/phone-numbers/available

Query parameters

countrystring

ISO code, or auto on the keyless shape to search the caller's own country (from their IP) near their city, falling back to US.

numberType'local' | 'mobile' | 'national' | 'toll_free'

Number type; defaults to the country's WhatsApp-safe type (the same name as on purchase, availability and kyc)

areaCodestring

Area code or national dialing code the number must start with, e.g. 415 or 91

typestring

Alias of numberType, kept for existing callers

prefixstring

Alias of areaCode, kept for existing callers

localitystring

City

containsstring

Pattern to match within the number

smsboolean

true narrows the pool to SMS-capable numbers. Each result still carries its full features list for per-number capability badging.

limitinteger
maskedboolean

true returns the keyless shape (masked numbers with claimId and claimUrl) even when you send an API key, e.g. to hand a user a signup link for a number.

Response

Available numbers.

countrystring
numberTypestring
requireSmsboolean

Echo of the sms filter applied to this search.

maskedboolean

true on keyless calls.

nearstring nullable

With country=auto: the caller's city the results were narrowed to, or null when there was no stock there.

claimIdstring

Keyless calls only: a claim for any number matching this search's country, type and area.

claimUrlstring

Keyless calls only: signup link for any number matching this search.

Changes

Changed in 3 of the 56 revisions of this API.16

  • 2c04683ce69410See the full diff
    • ○

      added the new optional query request parameter masked

      new-optional-request-parameter

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • dd3865482f9f4See the full diff
    • ○

      added the new optional query request parameter areaCode

      new-optional-request-parameter

    • ○

      added the new optional query request parameter numberType

      new-optional-request-parameter

    • ○

      query request parameter prefix was deprecated

      request-parameter-deprecated

    • ○

      query request parameter type was deprecated

      request-parameter-deprecated

  • e70ed06e71502See the full diff
    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added