Search available numbers
GET /v1/phone-lines/available lists the landline numbers that can be bought right now in one Brazilian area code (DDD). It is the first step of a purchase: the number of each result is exactly what POST /v1/phone-lines takes.
Requires a tenant-scoped key. With an OAuth / MCP token, only the workspace Owner may search (
phone_lines:purchase, the same permission as buying) — 403 PERMISSION_DENIED otherwise.Endpoint
GET https://pilotstatus.com.br/v1/phone-lines/available?ddd=11
Query parameters
string
required
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.Example
Response fields
string
The area code you searched, echoed back.
integer
How many numbers the carrier reports as available in this area code. Do not assume it equals the length of
numbers.object[]
The numbers returned by this search. Not paginated.
string
E.164 digits without
+: 55 + area code + 8 digits, e.g. 551148637200. Send this value to POST /v1/phone-lines.string
The same number formatted for people:
(11) 4863-7200.Good to know
- A search is not a reservation. A listed number can be bought by someone else before your purchase reaches it; that number then comes back in the purchase results as
NUMBER_UNAVAILABLE— without a charge, or, when the carrier had already sold it outside Pilot Status, with the price refunded to your wallet. Search again and pick another. - 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 the endpoint answers
503 SUPPLIER_UNAVAILABLE. - Identity verification is not required to search — only to buy. See Overview → identity verification.