> ## 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. # Leads do Meta Lead Ads > Lista os leads captados dos Formulários Instantâneos do Meta Lead Ads (Facebook / Instagram) nas Páginas do Facebook vinculadas, no painel da Pilot Status, ao número de WhatsApp da chave — mais recentes primeiro pelo `created_time` da Meta (empate desfeito pelo `id`, decrescente). Leads apagados nunca são listados nem contados. **Requer chave com escopo de número** (ou uma chave da conta restrita com `x-whatsapp-number-id`). Tokens OAuth/MCP também precisam da permissão `chat:read`: o papel ANALYST é recusado. `id` é o id do lead na Pilot Status (use-o em `GET /v1/leads/{id}`); `leadgenId` é o id da Meta. `createdAt` é quando a pessoa enviou o formulário na Meta, não quando a Pilot Status o guardou — um lead importado depois mantém a data original. `consentGiven` tem três estados: `true` = a pessoa marcou a caixa de consentimento configurada para aquele formulário; `false` = deixou desmarcada; `null` = DESCONHECIDO (nenhuma caixa configurada para o formulário quando o lead foi guardado, ou sem resposta) — nunca leia `null` como recusa. Privacidade (PII): um lead ocultado (`redacted: true`) mantém os ids, a atribuição (página, formulário, anúncio e os nomes resolvidos do anúncio) e os campos de status, mas `fullName`, `email` e `phone` voltam nulos e `fields` vazio. Num número RELAY_ONLY todos os leads vêm ocultados e a resposta traz `notice: "PII_RELAY_ONLY"`; em STORE_X_DAYS só os leads com `createdAt` anterior à janela são ocultados. `total` sempre conta todos os leads que atendem ao filtro. ## OpenAPI ````yaml openapi.pt.json GET /v1/leads 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/leads: get: tags: - Conversations summary: Listar leads do Meta Lead Ads description: >- Lista os leads captados dos Formulários Instantâneos do Meta Lead Ads (Facebook / Instagram) nas Páginas do Facebook vinculadas, no painel da Pilot Status, ao número de WhatsApp da chave — mais recentes primeiro pelo `created_time` da Meta (empate desfeito pelo `id`, decrescente). Leads apagados nunca são listados nem contados. **Requer chave com escopo de número** (ou uma chave da conta restrita com `x-whatsapp-number-id`). Tokens OAuth/MCP também precisam da permissão `chat:read`: o papel ANALYST é recusado. `id` é o id do lead na Pilot Status (use-o em `GET /v1/leads/{id}`); `leadgenId` é o id da Meta. `createdAt` é quando a pessoa enviou o formulário na Meta, não quando a Pilot Status o guardou — um lead importado depois mantém a data original. `consentGiven` tem três estados: `true` = a pessoa marcou a caixa de consentimento configurada para aquele formulário; `false` = deixou desmarcada; `null` = DESCONHECIDO (nenhuma caixa configurada para o formulário quando o lead foi guardado, ou sem resposta) — nunca leia `null` como recusa. Privacidade (PII): um lead ocultado (`redacted: true`) mantém os ids, a atribuição (página, formulário, anúncio e os nomes resolvidos do anúncio) e os campos de status, mas `fullName`, `email` e `phone` voltam nulos e `fields` vazio. Num número RELAY_ONLY todos os leads vêm ocultados e a resposta traz `notice: "PII_RELAY_ONLY"`; em STORE_X_DAYS só os leads com `createdAt` anterior à janela são ocultados. `total` sempre conta todos os leads que atendem ao filtro. operationId: get_leads parameters: - name: formId in: query required: false description: Filtra por um único id de Formulário Instantâneo. schema: type: string description: (string) example: '987654321098765' - name: adId in: query required: false description: Filtra por um único id de anúncio. schema: type: string description: (string) example: '120249828053880703' - name: pageId in: query required: false description: Filtra por um único id de Página do Facebook. schema: type: string description: (string) example: '102345678901234' - name: startDate in: query required: false description: >- Início do período, sobre o `createdAt` do lead (created_time da Meta), inclusive. Deve ser ≤ endDate. schema: type: string description: (string (ISO 8601)) example: '2026-10-01T00:00:00Z' - name: endDate in: query required: false description: Fim do período, sobre o `createdAt` do lead, inclusive. schema: type: string description: (string (ISO 8601)) example: '2026-10-20T23:59:59Z' - name: page in: query required: false description: Página (padrão 1). Valores abaixo de 1 ou não numéricos viram 1. schema: type: string description: (integer (≥1)) example: '1' - name: pageSize in: query required: false description: >- Itens por página (padrão 30, máximo 100; valores maiores são limitados a 100). schema: type: string description: (integer (1–100)) example: '30' responses: '200': description: Leads do número da chave content: application/json: example: leads: - id: cmg4x2k9a0001ab12cd34ef56 leadgenId: '1234567890123456' whatsappNumberId: num_01HZX... pageId: '102345678901234' pageName: MM Design formId: '987654321098765' formName: Orçamento — Outubro adId: '120249828053880703' adName: Ads 01 - Vídeo dos 70% adsetName: '[IG] [LL1% IG + VÍDEOS] - 35 a 50' campaignName: '[CD-01] [LEADS] - MM Design - Sale 70%' platform: ig isOrganic: false createdAt: '2026-10-18T14:32:10.000Z' fullName: Maria Souza email: maria@example.com phone: +55 11 91234-5678 fields: - key: full_name label: full_name values: - Maria Souza - key: qual_ambiente label: Qual ambiente você quer reformar? values: - Cozinha consentGiven: null conversationId: null autoSendStatus: none autoSendReason: null source: webhook redacted: false - id: cmg4x2k9a0002ab12cd34ef57 leadgenId: '1234567890654321' whatsappNumberId: num_01HZX... pageId: '102345678901234' pageName: MM Design formId: '987654321098765' formName: Orçamento — Outubro adId: null adName: null adsetName: null campaignName: null platform: fb isOrganic: true createdAt: '2026-10-17T09:05:44.000Z' fullName: null email: null phone: null fields: [] consentGiven: null conversationId: null autoSendStatus: none autoSendReason: null source: backfill redacted: true total: 2 page: 1 pageSize: 30 totalPages: 1 '400': description: >- Período inválido, paginação profunda demais ou chave sem número vinculado content: application/json: schema: type: object properties: error: type: string code: type: string example: error: startDate must be before or equal to endDate code: INVALID_DATE_RANGE '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: >- Credencial da conta sem `x-whatsapp-number-id`, ou token OAuth cujo papel no workspace não tem `chat:read` content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- This endpoint acts on a single WhatsApp number: send the x-whatsapp-number-id header naming the number to act on (its id or instance id from GET /v1/numbers) | Este endpoint atua sobre um único número de WhatsApp: envie o header x-whatsapp-number-id indicando o número desejado (o id dele ou o id da instância, obtidos em GET /v1/numbers) code: TENANT_SCOPE_NOT_ALLOWED 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.