Search available numbers

GET

/api/v2/numbers/search

curl --request GET \
  --url 'https://api.sipstack.com/api/v2/numbers/search?type=tollfree&areaCode=416' \
  --header 'x-api-key: <x-api-key>'

import requests

url = "https://api.sipstack.com/api/v2/numbers/search"

querystring = {"type":"tollfree","areaCode":"416"}

headers = {"x-api-key": "<x-api-key>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

const url = 'https://api.sipstack.com/api/v2/numbers/search?type=tollfree&areaCode=416';
const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.sipstack.com/api/v2/numbers/search',
  params: {type: 'tollfree', areaCode: '416'},
  headers: {'x-api-key': '<x-api-key>'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Searches carrier inventory for numbers you can buy. Search local numbers by areaCode (optionally contains / smsEnabled), or toll-free with type=tollfree (optionally tollFreePrefix / a vanity pattern). Read-only — no order is placed. The upstream carrier is never revealed. Requires numbers:read.

Authorizations

apiKeyAuth

Parameters

Query Parameters

type

string

Allowed values: tollfree

tollfree for toll-free search; omit for local.

areaCode

string

Example

Local search — the NPA to search within.

contains

string

Local — digits/letters the number must contain (vanity).

endsIn

boolean

Match contains at the end of the number.

smsEnabled

boolean

Only return SMS-capable numbers.

tollFreePrefix

string

Toll-free — restrict to a prefix (e.g. 800, 888).

vanity

string

Toll-free — a vanity pattern (e.g. 1-800-FLOWERS).

limit

integer

Responses

200

Matching available numbers.

application/json

object

success

boolean

data

Array<object>

An available number from carrier inventory (search result). The upstream carrier/provider is never included. Field set varies by number type.

object

number

string

rateCenter

string

nullable

city

string

nullable

state

string

nullable

smsEnabled

boolean

nullable

key

additional properties

any

Example

{
  "data": [
    {
      "number": "+14165550100"
    }
  ]
}

400

Invalid search parameters.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

401

Missing or invalid API key.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

403

The key is missing the numbers:read scope, or the account API tier is not on your plan.

application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}