Search available numbers
Lists the Brazilian landline numbers that can be bought right now in one area code (DDD). It is the first step of a purchase: the number of each result is exactly what POST /v1/phone-lines takes.
- A search is not a reservation. A listed number can be bought by someone else before your purchase reaches it; it then comes back in the purchase results as
NUMBER_UNAVAILABLE. - Every search reaches our carrier and draws on a request budget shared by the whole platform. Search once, show the list and reuse it — do not poll this endpoint. When the budget is exhausted it answers
503 SUPPLIER_UNAVAILABLE. - Identity verification is not required to search — only to buy.
Permissions: with an OAuth / MCP token, only the workspace Owner may search (phone_lines:purchase, the same permission as buying) — 403 PERMISSION_DENIED otherwise. A classic ps_ tenant key has no user and no role: its authority is its scope.
Every /v1/phone-lines endpoint takes a tenant-scoped key only: a line belongs to the workspace, not to a WhatsApp number, so a number-scoped key (or a per-number OAuth grant) gets 403 NUMBER_SCOPE_NOT_ALLOWED before any role is looked at. A 403 PERMISSION_DENIED / WORKSPACE_MEMBERSHIP_REQUIRED is sent with Cache-Control: no-store.
Requires a tenant-scoped key.
curl --request GET \
--url https://pilotstatus.com.br/v1/phone-lines/available \
--header 'x-api-key: <api-key>'import requests
url = "https://pilotstatus.com.br/v1/phone-lines/available"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://pilotstatus.com.br/v1/phone-lines/available', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://pilotstatus.com.br/v1/phone-lines/available",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://pilotstatus.com.br/v1/phone-lines/available"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://pilotstatus.com.br/v1/phone-lines/available")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://pilotstatus.com.br/v1/phone-lines/available")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"ddd": "11",
"totalAvailable": 2,
"numbers": [
{
"number": "551148637200",
"display": "(11) 4863-7200"
},
{
"number": "551148637201",
"display": "(11) 4863-7201"
}
],
"price": 33.9,
"currency": "BRL"
}Authorizations
Your ps_ API key
Query Parameters
The two-digit area code, first digit 1–9 (e.g. 11, 21, 31). Missing or malformed → 400 INVALID_AREA_CODE, and the carrier is not called.
^[1-9][0-9]$Response
Numbers available in the area code
The area code you searched, echoed back.
"11"
How many numbers the carrier reports as available in this area code. Do not assume it equals the length of numbers.
2
The numbers returned by this search. Not paginated.
Show child attributes
Show child attributes
Monthly price of ONE new line for this workspace, shown before the purchase. Honors the workspace's own phone line price set by the Pilot Status team; it is the same amount POST /v1/phone-lines charges.
33.9
The workspace's currency — the currency of price and of the purchase.
BRL, USD "BRL"
Was this page helpful?
curl --request GET \
--url https://pilotstatus.com.br/v1/phone-lines/available \
--header 'x-api-key: <api-key>'import requests
url = "https://pilotstatus.com.br/v1/phone-lines/available"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://pilotstatus.com.br/v1/phone-lines/available', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://pilotstatus.com.br/v1/phone-lines/available",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://pilotstatus.com.br/v1/phone-lines/available"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://pilotstatus.com.br/v1/phone-lines/available")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://pilotstatus.com.br/v1/phone-lines/available")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"ddd": "11",
"totalAvailable": 2,
"numbers": [
{
"number": "551148637200",
"display": "(11) 4863-7200"
},
{
"number": "551148637201",
"display": "(11) 4863-7201"
}
],
"price": 33.9,
"currency": "BRL"
}