Lead Ads Pages API — Facebook Pages and Instant Forms

​

Endpoints

​

Before you link: sharing and ownership

1. shares the Page with the Pilot Status business portfolio — the partnerBusinessId that GET /v1/lead-pages returns — in Meta Business Manager;
2. gives the Pilot Status system user the Page tasks it needs. candidates[].missingTasks lists what is still missing: MODERATE, MANAGE_LEADS, or PAGE_ACCESS when the Page was not assigned to the system user at all. An empty list means ready; null means Meta could not be asked.

​

Credentials and permissions

• OAuth/MCP tokens need integrations:manage (workspace ADMIN or OWNER) on every endpoint, reads included — ANALYST and AGENT are refused with 403 PERMISSION_DENIED. A classic ps_ key has no role and passes by its scope.
• Scope: a number-scoped key, or an account-wide credential with the x-whatsapp-number-id header, sees and changes only the links of that number. An account-wide credential without the header sees the whole workspace and names the number in the body. A link on a number outside the credential’s scope answers 403 NUMBER_NOT_IN_GRANT.

​

GET /v1/lead-pages

{
  "linked": [
    {
      "pageLinkId": "cmgpl0001ab12cd34ef56",
      "pageId": "102345678901234",
      "pageName": "MM Design",
      "whatsappNumberId": "num_01HZX...",
      "subscribedAt": "2026-10-06T10:15:00.000Z",
      "subscriptionError": null,
      "linkedAt": "2026-10-06T10:14:58.000Z",
      "leadsCount": 42
    }
  ],
  "candidates": [
    { "pageId": "109876543210987", "pageName": "MM Design Outlet", "missingTasks": ["MANAGE_LEADS"] }
  ],
  "configured": true,
  "partnerBusinessId": "123456789012345",
  "candidatesLookup": "ok",
  "eligibilityBlocker": null
}

​

POST /v1/lead-pages

curl -X POST https://pilotstatus.com.br/v1/lead-pages \
  -H "x-api-key: ps_..." \
  -H "Content-Type: application/json" \
  -d '{ "pageId": "109876543210987", "whatsappNumberId": "num_01HZX..." }'

• pageId is the numeric Facebook Page id. whatsappNumberId may be left out only when the credential is bound to one number. Any other field is refused with 400 UNKNOWN_FIELDS.
• Ownership and the Page tasks are checked before anything is written: 409 PAGE_NOT_ELIGIBLE (with reason when known; without one when another workspace already linked the Page), 409 PAGE_MISSING_PERMISSION (with missingTasks), 409 PAGE_ALREADY_LINKED (with the existing pageLinkId).
• On success (201 { "link": { … } }) Pilot Status subscribes to the Page’s leads and starts pulling its last 90 days of leads in the background. If Meta refuses the subscription, the link is still created and subscriptionError says why.

​

PATCH /v1/lead-pages/{pageLinkId}

​

DELETE /v1/lead-pages/{pageLinkId}

​

POST /v1/lead-pages/{pageLinkId}/resync

{ "started": true, "pageLinkId": "cmgpl0001ab12cd34ef56", "subscribedAt": "2026-10-21T10:02:44.000Z", "subscriptionError": null }

• One resync per link every 10 minutes. Inside that window the answer is 429 RESYNC_COOLDOWN with retryAfterSeconds. If the wait cannot be checked, the answer is 503 RESYNC_UNAVAILABLE, never an unbounded resync.
• Ownership is checked again. A Page that is no longer eligible is flagged on the link (subscriptionError) and answers 409 PAGE_NOT_ELIGIBLE with reason.

​

GET /v1/lead-pages/{pageLinkId}/forms

• consentAvailable: false — the form’s checkboxes could not be read. The list is unknown, not empty.
• formsTruncated: true — the Page has more forms than Pilot Status read.

​

PUT /v1/lead-pages/{pageLinkId}/forms/{formId}

{
  "consentDisclaimerKey": "whatsapp_optin",
  "autoSendEnabled": true,
  "templateId": null,
  "freeText": "Olá {{nome}}, recebemos seu pedido de orçamento!",
  "variableMap": { "nome": { "source": "field", "key": "full_name" } },
  "formName": "Orçamento — Outubro"
}

​

Errors