> ## 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. # Vincular Página do Lead Ads > Vincula uma Página do Facebook a um número de WhatsApp do workspace, inscreve a Pilot Status nos leads da Página e começa a buscar os leads dos últimos 90 dias em segundo plano. Corpo: `pageId` (o id numérico da Página do Facebook) e `whatsappNumberId`. `whatsappNumberId` só pode ser omitido quando a credencial está vinculada a um número (chave com escopo de número, ou `x-whatsapp-number-id`); um número fora do escopo da credencial é `403 NUMBER_NOT_IN_GRANT`. Qualquer outro campo é recusado com `400 UNKNOWN_FIELDS`. Posse e permissões são conferidas antes de gravar qualquer coisa: `409 PAGE_NOT_ELIGIBLE` (com `reason` quando conhecido: `NO_OFFICIAL_NUMBER`, `PAGE_NOT_SHARED`, `PAGE_BUSINESS_MISMATCH`; sem `reason` quando outro workspace já a vinculou), `409 PAGE_MISSING_PERMISSION` (com `missingTasks`), `409 PAGE_ALREADY_LINKED` (com o `pageLinkId` existente). Se a Meta recusar a inscrição, o vínculo é criado mesmo assim e o motivo volta em `subscriptionError` — a ressincronização tenta de novo. Tokens OAuth/MCP precisam de `integrations:manage` (ADMIN ou OWNER do workspace) em todos os verbos, leituras incluídas. Escopo: uma chave com escopo de número, ou uma credencial da conta inteira com `x-whatsapp-number-id`, atua só nos vínculos daquele número; uma credencial da conta inteira sem o header vê o workspace todo. ## OpenAPI ````yaml openapi.pt.json POST /v1/lead-pages openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/lead-pages: post: tags: - Ads summary: Vincular Página do Lead Ads description: >- Vincula uma Página do Facebook a um número de WhatsApp do workspace, inscreve a Pilot Status nos leads da Página e começa a buscar os leads dos últimos 90 dias em segundo plano. Corpo: `pageId` (o id numérico da Página do Facebook) e `whatsappNumberId`. `whatsappNumberId` só pode ser omitido quando a credencial está vinculada a um número (chave com escopo de número, ou `x-whatsapp-number-id`); um número fora do escopo da credencial é `403 NUMBER_NOT_IN_GRANT`. Qualquer outro campo é recusado com `400 UNKNOWN_FIELDS`. Posse e permissões são conferidas antes de gravar qualquer coisa: `409 PAGE_NOT_ELIGIBLE` (com `reason` quando conhecido: `NO_OFFICIAL_NUMBER`, `PAGE_NOT_SHARED`, `PAGE_BUSINESS_MISMATCH`; sem `reason` quando outro workspace já a vinculou), `409 PAGE_MISSING_PERMISSION` (com `missingTasks`), `409 PAGE_ALREADY_LINKED` (com o `pageLinkId` existente). Se a Meta recusar a inscrição, o vínculo é criado mesmo assim e o motivo volta em `subscriptionError` — a ressincronização tenta de novo. Tokens OAuth/MCP precisam de `integrations:manage` (ADMIN ou OWNER do workspace) em todos os verbos, leituras incluídas. Escopo: uma chave com escopo de número, ou uma credencial da conta inteira com `x-whatsapp-number-id`, atua só nos vínculos daquele número; uma credencial da conta inteira sem o header vê o workspace todo. operationId: post_lead-pages parameters: - name: x-whatsapp-number-id in: header required: false description: >- Restringe uma credencial da conta inteira a um número (o id dele ou o id da instância, de `GET /v1/numbers`). Sem ele, uma credencial da conta inteira vê o workspace todo; uma chave com escopo de número vê sempre só o próprio número. schema: type: string example: num_01HZX... requestBody: required: true content: application/json: schema: type: object properties: pageId: type: string pattern: ^\d+$ description: Id numérico da Página do Facebook (de `candidates`). example: '109876543210987' whatsappNumberId: type: string description: >- Número que recebe os leads da Página. Opcional quando a credencial está vinculada a um número. example: num_01HZX... required: - pageId additionalProperties: false responses: '201': description: Página vinculada content: application/json: example: link: pageLinkId: cmgpl0001ab12cd34ef56 pageId: '109876543210987' pageName: MM Design Outlet whatsappNumberId: num_01HZX... subscribedAt: '2026-10-06T10:15:00.000Z' subscriptionError: null linkedAt: '2026-10-06T10:14:58.000Z' leadsCount: 0 '400': description: >- `INVALID_BODY`, `UNKNOWN_FIELDS` (com `unknownFields`), `VALIDATION_FAILED` (`pageId` não numérico, ou sem `whatsappNumberId` numa credencial não vinculada a um número), ou `NUMBER_REQUIRED` (concessão OAuth por número sem `x-whatsapp-number-id`) ou `NUMBER_NOT_FOUND` (chave com escopo de número cujo número foi apagado) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Validation failed | Falha na validação code: VALIDATION_FAILED '401': description: Header `x-api-key` / `x-api-key-id` ausente ou inválido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '403': description: >- O número está fora do escopo da credencial (`NUMBER_NOT_IN_GRANT`), ou token OAuth cujo papel no workspace não tem `integrations:manage` (`PERMISSION_DENIED`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- This credential is not granted access to that WhatsApp number | Esta credencial não tem acesso a esse número de WhatsApp code: NUMBER_NOT_IN_GRANT '404': description: '`whatsappNumberId` não é um número deste workspace' content: application/json: schema: type: object properties: error: type: string code: type: string example: error: WhatsApp number not found | Número de WhatsApp não encontrado code: NUMBER_NOT_FOUND '409': description: >- `PAGE_ALREADY_LINKED` (com `pageLinkId`), `PAGE_NOT_ELIGIBLE` (com `reason` quando conhecido) ou `PAGE_MISSING_PERMISSION` (com `missingTasks`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Pilot Status does not have the required permissions on this Page yet. | A Pilot Status ainda não tem as permissões necessárias nesta página. code: PAGE_MISSING_PERMISSION missingTasks: - MANAGE_LEADS '500': description: Erro interno content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Internal server error | Erro interno do servidor code: INTERNAL_ERROR '502': description: Não foi possível consultar a Meta. Tente de novo. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Could not reach Meta right now. Try again. | Não foi possível consultar a Meta agora. Tente novamente. code: LEADS_LOOKUP_UNAVAILABLE '503': description: A captura de leads não está configurada nesta instalação content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Meta lead capture is not configured on this installation. | Captura de leads da Meta não configurada nesta instalação. code: LEADS_NOT_CONFIGURED components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.