> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # 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.** ## OpenAPI ````yaml openapi.json GET /v1/phone-lines/available openapi: 3.1.0 info: title: Pilot Status API version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- Public REST API for Pilot Status. Authenticate with the `x-api-key: ps_...` header (or `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/phone-lines/available: get: tags: - Phone Lines summary: Search available numbers description: >- 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.** operationId: get_phone_lines_available parameters: - name: ddd in: query required: true description: >- 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. schema: type: string pattern: ^[1-9][0-9]$ example: '11' responses: '200': description: Numbers available in the area code content: application/json: schema: type: object properties: ddd: type: string description: The area code you searched, echoed back. example: '11' totalAvailable: type: integer description: >- How many numbers the carrier reports as available in this area code. Do not assume it equals the length of `numbers`. example: 2 numbers: type: array description: The numbers returned by this search. Not paginated. items: type: object properties: number: type: string description: >- E.164 digits **without** `+`: `55` + area code + 8 digits, e.g. `551148637200`. Send this value to `POST /v1/phone-lines`. example: '551148637200' display: type: string description: >- The same number formatted for people: `(11) 4863-7200`. example: (11) 4863-7200 price: type: number example: 33.9 description: >- 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. currency: type: string enum: - BRL - USD example: BRL description: >- The workspace's currency — the currency of `price` and of the purchase. example: ddd: '11' totalAvailable: 2 numbers: - number: '551148637200' display: (11) 4863-7200 - number: '551148637201' display: (11) 4863-7201 price: 33.9 currency: BRL '400': description: '`ddd` missing, or not two digits starting 1–9 (`INVALID_AREA_CODE`)' content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Invalid area code. | DDD inválido. code: INVALID_AREA_CODE '401': description: >- Missing or invalid credential (`x-api-key`, `x-api-key-id` or `Authorization: Bearer`). The body carries only `error`, no `code`. content: application/json: schema: type: object properties: error: type: string code: type: string examples: missing: summary: No credential value: error: >- Missing x-api-key, x-api-key-id or Authorization Bearer token invalid: summary: Invalid API key value: error: Invalid API key '403': description: >- Number-scoped key (`NUMBER_SCOPE_NOT_ALLOWED`), OAuth/MCP token of a user who is not the workspace Owner (`PERMISSION_DENIED`) or no longer an active member (`WORKSPACE_MEMBERSHIP_REQUIRED`), or archived workspace (`WORKSPACE_ARCHIVED`). `TENANT_REQUIRED`: credential not bound to any workspace content: application/json: schema: type: object properties: error: type: string code: type: string examples: numberScope: summary: Number-scoped key value: error: This endpoint requires a tenant-scoped API key code: NUMBER_SCOPE_NOT_ALLOWED permissionDenied: summary: OAuth/MCP user who is not the Owner value: error: >- Your workspace role does not allow this action (phone_lines:purchase). code: PERMISSION_DENIED notMember: summary: OAuth/MCP user no longer a member value: error: >- The user behind this token is not an active member of this workspace. code: WORKSPACE_MEMBERSHIP_REQUIRED archived: summary: Workspace archived value: error: >- This workspace has been archived and its API is closed. | Este workspace foi arquivado e sua API está encerrada. code: WORKSPACE_ARCHIVED tenantRequired: summary: Credential not bound to a workspace value: error: This credential is not bound to a workspace. code: TENANT_REQUIRED '404': description: >- An `x-whatsapp-number-id` header was sent and names no WhatsApp number of your account (`NUMBER_NOT_FOUND`). This endpoint needs no such header — remove it. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- x-whatsapp-number-id does not name a WhatsApp number of this account | x-whatsapp-number-id não indica um número de WhatsApp desta conta code: NUMBER_NOT_FOUND '500': description: Unexpected failure (`INTERNAL_ERROR`). content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unexpected error. | Erro inesperado. code: INTERNAL_ERROR '503': description: >- The carrier could not answer, or the request budget shared by the whole platform ran out (`SUPPLIER_UNAVAILABLE`). Retry in a few minutes. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Phone lines are temporarily unavailable. Try again in a few minutes. | As linhas estão temporariamente indisponíveis. Tente de novo em alguns minutos. code: SUPPLIER_UNAVAILABLE components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your ps_ API key apiKeyId: type: apiKey in: header name: x-api-key-id description: API key id (alternative to x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.