> ## 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. # Request activation code > Gets the line ready to capture a NEW WhatsApp verification call — no body. WhatsApp verifies a landline **by calling it** and speaking a 6-digit code; this endpoint opens the capture window, it does **not** place the call. The line is reset at the carrier, so the recording of an earlier call can never be read as this one's code, and a request opens in `WAITING` until `pollDeadline` — **5 minutes** later. A call that arrives before this request exists is not captured. After the `201`, register the number in WhatsApp Business and choose the **phone call** option ("Call me") — the line is a landline and does not receive SMS. Then poll `GET /v1/phone-lines/activations/{activationId}` every few seconds (or listen for the `phone_line.code_received` webhook) and type `code` into WhatsApp. Allowed while the line is `ACTIVE` or `PAYMENT_PENDING`; a `SUSPENDED`, `RETURNED` or `CANCELED` line gets `409 LINE_NOT_ACTIVE`. **One waiting request per line:** while a request is `WAITING` and its `pollDeadline` is still ahead, another `POST` answers `409 ACTIVATION_IN_PROGRESS` — poll the one you have, or cancel it with `POST /v1/phone-lines/{id}/activations/{activationId}/cancel` to ask again right away. No limit on requests over time; each request that opens increments the line's `activationCount`. Sent with `Cache-Control: no-store`: the code is a credential. **Requires a tenant-scoped key** — a number-scoped key (or per-number OAuth grant) gets `403 NUMBER_SCOPE_NOT_ALLOWED`. Permission `phone_lines:read`: with an OAuth / MCP token the user must be an **Owner or Admin** (`403 PERMISSION_DENIED` otherwise). ## OpenAPI ````yaml openapi.json POST /v1/phone-lines/{id}/activations 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/{id}/activations: post: tags: - Phone Lines summary: Request an activation code description: >- Gets the line ready to capture a NEW WhatsApp verification call — no body. WhatsApp verifies a landline **by calling it** and speaking a 6-digit code; this endpoint opens the capture window, it does **not** place the call. The line is reset at the carrier, so the recording of an earlier call can never be read as this one's code, and a request opens in `WAITING` until `pollDeadline` — **5 minutes** later. A call that arrives before this request exists is not captured. After the `201`, register the number in WhatsApp Business and choose the **phone call** option ("Call me") — the line is a landline and does not receive SMS. Then poll `GET /v1/phone-lines/activations/{activationId}` every few seconds (or listen for the `phone_line.code_received` webhook) and type `code` into WhatsApp. Allowed while the line is `ACTIVE` or `PAYMENT_PENDING`; a `SUSPENDED`, `RETURNED` or `CANCELED` line gets `409 LINE_NOT_ACTIVE`. **One waiting request per line:** while a request is `WAITING` and its `pollDeadline` is still ahead, another `POST` answers `409 ACTIVATION_IN_PROGRESS` — poll the one you have, or cancel it with `POST /v1/phone-lines/{id}/activations/{activationId}/cancel` to ask again right away. No limit on requests over time; each request that opens increments the line's `activationCount`. Sent with `Cache-Control: no-store`: the code is a credential. **Requires a tenant-scoped key** — a number-scoped key (or per-number OAuth grant) gets `403 NUMBER_SCOPE_NOT_ALLOWED`. Permission `phone_lines:read`: with an OAuth / MCP token the user must be an **Owner or Admin** (`403 PERMISSION_DENIED` otherwise). operationId: post_phone_lines_id_activations parameters: - name: id in: path required: true schema: type: string example: cmg5k2l1n0001pl8example9x description: The line `id` (from `GET /v1/phone-lines`) — not the phone number. responses: '201': description: >- Code request opened (`WAITING`). Sent with `Cache-Control: no-store`. headers: Cache-Control: description: '`no-store`' schema: type: string enum: - no-store content: application/json: schema: type: object properties: activation: type: object properties: id: type: string description: The request id (`activationId`). lineId: type: string description: The line the request belongs to. status: type: string enum: - WAITING - CAPTURED - TRANSCRIBED - TIMED_OUT - FAILED description: >- `WAITING`, `CAPTURED`, `TRANSCRIBED`, `TIMED_OUT` or `FAILED`. Keep polling while `status` is `WAITING`, or `CAPTURED` with `failureReason: null`; every other combination is final. requestedAt: type: string format: date-time description: ISO 8601 — when the request was opened. pollDeadline: type: string format: date-time description: >- ISO 8601 — end of the capture window, 5 minutes after the request. code: type: - string - 'null' description: >- The 6-digit code, once `TRANSCRIBED` and found. `null` otherwise. **A credential** — whoever holds it can register a WhatsApp account on the line. capturedAt: type: - string - 'null' format: date-time description: ISO 8601 — when the call recording was stored. transcribedAt: type: - string - 'null' format: date-time description: ISO 8601 — when the transcription finished. failureReason: type: - string - 'null' description: >- Why a final request has no code: `no_call_in_window`, `canceled_by_customer`, `no_code_in_transcript`, `transcription_failed`, `audio_download_failed`, `audio_store_failed`, `poll_not_scheduled`, or `null`. Treat an unknown value as a failure, since new ones may be added. hasAudio: type: boolean description: >- Whether a recording of the call is stored — downloadable from `GET /v1/phone-lines/activations/{activationId}/audio` and playable in the dashboard. required: - id - lineId - status - requestedAt - pollDeadline - code - capturedAt - transcribedAt - failureReason - hasAudio required: - activation example: activation: id: cmg5k3a7c0002ac8example4q lineId: cmg5k2l1n0001pl8example9x status: WAITING requestedAt: '2026-10-01T14:10:00.000Z' pollDeadline: '2026-10-01T14:15:00.000Z' code: null capturedAt: null transcribedAt: null failureReason: null hasAudio: false '401': description: >- Missing or invalid `x-api-key` / `x-api-key-id` header (the body carries only `error`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Invalid API key '403': description: >- Number-scoped key or per-number OAuth grant (`NUMBER_SCOPE_NOT_ALLOWED`); OAuth/MCP token of a user who is not Owner or Admin (`PERMISSION_DENIED`) or no longer an active member (`WORKSPACE_MEMBERSHIP_REQUIRED`); 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: number_scope_not_allowed: summary: Number-scoped key value: error: This endpoint requires a tenant-scoped API key code: NUMBER_SCOPE_NOT_ALLOWED permission_denied: summary: Role without phone_lines:read value: error: >- Your workspace role does not allow this action (phone_lines:read). code: PERMISSION_DENIED workspace_membership_required: summary: No longer a member value: error: >- The user behind this token is not an active member of this workspace. code: WORKSPACE_MEMBERSHIP_REQUIRED workspace_archived: summary: Archived workspace 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: >- No such line in your workspace (another workspace's line reads the same) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Line not found. | Linha não encontrada. code: LINE_NOT_FOUND '409': description: >- `LINE_NOT_ACTIVE` — the line is `SUSPENDED`, `RETURNED` or `CANCELED`, nothing was created; `ACTIVATION_IN_PROGRESS` — a request on this line is still waiting for the call: poll it, or cancel it to ask again now content: application/json: schema: type: object properties: error: type: string code: type: string examples: activation_in_progress: summary: A request is already waiting value: error: >- A code request is already waiting for the call on this line. | Já existe um pedido de código esperando a ligação nesta linha. code: ACTIVATION_IN_PROGRESS line_not_active: summary: Line SUSPENDED, RETURNED or CANCELED value: error: >- This line is not active, so it cannot receive a new code. | Esta linha não está ativa, então não pode receber um novo código. code: LINE_NOT_ACTIVE '500': description: Unexpected failure 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 reset the line (nothing created), or we could not start watching it (a `FAILED` request with `poll_not_scheduled` stays in the history). Retry — a new `POST` is allowed right away. 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.