> ## 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. # Link a Lead Ads Page > Links one Facebook Page to one WhatsApp number of the workspace, subscribes Pilot Status to the Page's leads and starts pulling its last 90 days of leads in the background. Body: `pageId` (the numeric Facebook Page id) and `whatsappNumberId`. `whatsappNumberId` may be omitted only when the credential is bound to one number (a number-scoped key, or `x-whatsapp-number-id`); a number outside the credential's scope is `403 NUMBER_NOT_IN_GRANT`. Any other field is refused with `400 UNKNOWN_FIELDS`. Ownership and permissions are checked before anything is written: `409 PAGE_NOT_ELIGIBLE` (with `reason` when known: `NO_OFFICIAL_NUMBER`, `PAGE_NOT_SHARED`, `PAGE_BUSINESS_MISMATCH`; no `reason` when another workspace already linked it), `409 PAGE_MISSING_PERMISSION` (with `missingTasks`), `409 PAGE_ALREADY_LINKED` (with the existing `pageLinkId`). If Meta refuses the subscription, the link is still created and the reason is returned in `subscriptionError` — resync retries it. OAuth/MCP tokens need `integrations:manage` (workspace ADMIN or OWNER) on every verb, reads included. Scope: a number-scoped key, or an account-wide credential with `x-whatsapp-number-id`, acts only on that number's links; an account-wide credential without the header sees the whole workspace. ## OpenAPI ````yaml openapi.json POST /v1/lead-pages 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/lead-pages: post: tags: - Ads summary: Link a Lead Ads Page description: >- Links one Facebook Page to one WhatsApp number of the workspace, subscribes Pilot Status to the Page's leads and starts pulling its last 90 days of leads in the background. Body: `pageId` (the numeric Facebook Page id) and `whatsappNumberId`. `whatsappNumberId` may be omitted only when the credential is bound to one number (a number-scoped key, or `x-whatsapp-number-id`); a number outside the credential's scope is `403 NUMBER_NOT_IN_GRANT`. Any other field is refused with `400 UNKNOWN_FIELDS`. Ownership and permissions are checked before anything is written: `409 PAGE_NOT_ELIGIBLE` (with `reason` when known: `NO_OFFICIAL_NUMBER`, `PAGE_NOT_SHARED`, `PAGE_BUSINESS_MISMATCH`; no `reason` when another workspace already linked it), `409 PAGE_MISSING_PERMISSION` (with `missingTasks`), `409 PAGE_ALREADY_LINKED` (with the existing `pageLinkId`). If Meta refuses the subscription, the link is still created and the reason is returned in `subscriptionError` — resync retries it. OAuth/MCP tokens need `integrations:manage` (workspace ADMIN or OWNER) on every verb, reads included. Scope: a number-scoped key, or an account-wide credential with `x-whatsapp-number-id`, acts only on that number's links; an account-wide credential without the header sees the whole workspace. operationId: post_lead-pages parameters: - name: x-whatsapp-number-id in: header required: false description: >- Narrows an account-wide credential to one number (its id or instance id from `GET /v1/numbers`). Without it, an account-wide credential sees the whole workspace; a number-scoped key always sees only its own number. schema: type: string example: num_01HZX... requestBody: required: true content: application/json: schema: type: object properties: pageId: type: string pattern: ^\d+$ description: Numeric Facebook Page id (from `candidates`). example: '109876543210987' whatsappNumberId: type: string description: >- Number that receives the Page's leads. Optional when the credential is bound to one number. example: num_01HZX... required: - pageId additionalProperties: false responses: '201': description: Page linked 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` (with `unknownFields`), `VALIDATION_FAILED` (`pageId` not numeric, or no `whatsappNumberId` on a credential not bound to one number), or `NUMBER_REQUIRED` (a per-number OAuth grant without `x-whatsapp-number-id`) or `NUMBER_NOT_FOUND` (a number-scoped key whose number was deleted) 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: Missing or invalid `x-api-key` / `x-api-key-id` header content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '403': description: >- The number is outside the credential's scope (`NUMBER_NOT_IN_GRANT`), or an OAuth token whose workspace role lacks `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` is not a number of this 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` (with `pageLinkId`), `PAGE_NOT_ELIGIBLE` (with `reason` when known) or `PAGE_MISSING_PERMISSION` (with `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: Internal error 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: Meta could not be reached. Retry. 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: Lead capture is not configured on this installation 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: 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.