> ## 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. # Meta Lead Ads leads > Lists the leads captured from Meta Lead Ads Instant Forms (Facebook / Instagram) on the Facebook Pages linked, in the Pilot Status dashboard, to the key's WhatsApp number — newest first by Meta's `created_time` (ties broken by `id`, descending). Erased leads are never listed nor counted. **Requires a number-scoped key** (or an account-wide key narrowed with `x-whatsapp-number-id`). OAuth/MCP tokens also need the `chat:read` permission: the ANALYST role is refused. `id` is the Pilot Status lead id (use it on `GET /v1/leads/{id}`); `leadgenId` is Meta's id. `createdAt` is when the person submitted the form on Meta, not when Pilot Status stored it — a backfilled lead keeps its original date. `consentGiven` has three states: `true` = the person ticked the consent checkbox configured for that form; `false` = they left it unticked; `null` = UNKNOWN (no checkbox configured for the form when the lead was stored, or no answer) — never read `null` as a refusal. Privacy (PII): a redacted lead (`redacted: true`) keeps its ids, its attribution (page, form, ad and the resolved ad names) and its status fields, but `fullName`, `email` and `phone` come back null and `fields` empty. On a RELAY_ONLY number every lead is redacted and the response carries `notice: "PII_RELAY_ONLY"`; on STORE_X_DAYS only leads whose `createdAt` is older than the window are redacted. `total` always counts every lead that matches the filter. ## OpenAPI ````yaml openapi.json GET /v1/leads 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/leads: get: tags: - Conversations summary: List Meta Lead Ads leads description: >- Lists the leads captured from Meta Lead Ads Instant Forms (Facebook / Instagram) on the Facebook Pages linked, in the Pilot Status dashboard, to the key's WhatsApp number — newest first by Meta's `created_time` (ties broken by `id`, descending). Erased leads are never listed nor counted. **Requires a number-scoped key** (or an account-wide key narrowed with `x-whatsapp-number-id`). OAuth/MCP tokens also need the `chat:read` permission: the ANALYST role is refused. `id` is the Pilot Status lead id (use it on `GET /v1/leads/{id}`); `leadgenId` is Meta's id. `createdAt` is when the person submitted the form on Meta, not when Pilot Status stored it — a backfilled lead keeps its original date. `consentGiven` has three states: `true` = the person ticked the consent checkbox configured for that form; `false` = they left it unticked; `null` = UNKNOWN (no checkbox configured for the form when the lead was stored, or no answer) — never read `null` as a refusal. Privacy (PII): a redacted lead (`redacted: true`) keeps its ids, its attribution (page, form, ad and the resolved ad names) and its status fields, but `fullName`, `email` and `phone` come back null and `fields` empty. On a RELAY_ONLY number every lead is redacted and the response carries `notice: "PII_RELAY_ONLY"`; on STORE_X_DAYS only leads whose `createdAt` is older than the window are redacted. `total` always counts every lead that matches the filter. operationId: get_leads parameters: - name: formId in: query required: false description: Filter to a single Instant Form id. schema: type: string description: (string) example: '987654321098765' - name: adId in: query required: false description: Filter to a single ad id. schema: type: string description: (string) example: '120249828053880703' - name: pageId in: query required: false description: Filter to a single Facebook Page id. schema: type: string description: (string) example: '102345678901234' - name: startDate in: query required: false description: >- Start of the date range, over the lead's `createdAt` (Meta's created_time), inclusive. Must be ≤ endDate. schema: type: string description: (string (ISO 8601)) example: '2026-10-01T00:00:00Z' - name: endDate in: query required: false description: End of the date range, over the lead's `createdAt`, inclusive. schema: type: string description: (string (ISO 8601)) example: '2026-10-20T23:59:59Z' - name: page in: query required: false description: Page (default 1). Values below 1 or non-numeric fall back to 1. schema: type: string description: (integer (≥1)) example: '1' - name: pageSize in: query required: false description: >- Items per page (default 30, max 100; larger values are capped at 100). schema: type: string description: (integer (1–100)) example: '30' responses: '200': description: Leads of the key's number 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: >- Invalid date range, pagination too deep, or key not bound to a number 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: 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: >- Account-wide credential without `x-whatsapp-number-id`, or an OAuth token whose workspace role lacks `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: 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.