Ads API — Meta ad accounts and the per-ad summary

• Ad accounts — connect the Meta ad accounts whose ads bring people to your numbers, so Pilot Status can resolve each ad’s name, its ad set and its campaign.
• Ads summary — Click-to-WhatsApp traffic grouped by ad: conversations, messages, the resolved names and how many Lead Ads leads each ad produced.

​

Endpoints

​

No Meta login: partner sharing

​

Credentials and permissions

​

GET /v1/ads/accounts

curl https://pilotstatus.com.br/v1/ads/accounts \
  -H "x-api-key: ps_..."

{
  "linked": [
    {
      "adAccountId": "act_1234567890",
      "adAccountName": "MM Design",
      "linkedAt": "2026-10-05T14:02:11.000Z",
      "sharingActive": true
    }
  ],
  "candidates": [
    { "adAccountId": "act_9876543210", "adAccountName": "MM Design — Black Friday", "accountStatus": 1 }
  ],
  "partnerBusinessId": "123456789012345",
  "sharingLookup": "ok"
}

• sharingActive — true while the partner grant is in place, false when the advertiser revoked it on Meta, and null when Meta could not be asked right now. Never read null as revoked.
• candidates — accounts shared with Pilot Status that provably belong to your workspace, because an ad from them already reached one of your numbers, and are not linked yet. A new workspace starts with an empty list; link your account by its id.
• sharingLookup — ok, unavailable (Meta did not answer; linked still comes back) or not_configured.

​

POST /v1/ads/accounts

curl -X POST https://pilotstatus.com.br/v1/ads/accounts \
  -H "x-api-key: ps_..." \
  -H "Content-Type: application/json" \
  -d '{ "adAccountId": "act_1234567890" }'

1. The account must be yours. If no ad from it reached your conversations yet, the answer is 409 AD_ACCOUNT_NOT_PROVEN — contact support to link it.
2. The partner grant must have reached Meta. Otherwise 409 AD_ACCOUNT_NOT_SHARED.

​

DELETE /v1/ads/accounts/{adAccountId}

​

GET /v1/ads/summary

curl "https://pilotstatus.com.br/v1/ads/summary?startDate=2026-10-01T00:00:00Z" \
  -H "x-api-key: ps_..."

{
  "ads": [
    {
      "sourceId": "120249828053880703",
      "sourceType": "ad",
      "conversations": 37,
      "messages": 214,
      "firstAt": "2026-10-02T11:04:19.000Z",
      "lastAt": "2026-10-20T22:41:07.000Z",
      "lastSourceUrl": "https://fb.me/2bXyZ",
      "lastHeadline": "Reforma com 70% de desconto",
      "adName": "Ads 01 - Vídeo dos 70%",
      "adsetId": "120249828053880001",
      "adsetName": "[IG] [LL1% IG + VÍDEOS] - 35 a 50",
      "campaignId": "120249828053870000",
      "campaignName": "[CD-01] [LEADS] - MM Design - Sale 70%",
      "namesResolvedAt": "2026-10-20T23:00:02.000Z",
      "leadCount": 12
    }
  ],
  "total": 1,
  "limit": 200,
  "truncated": false
}

• conversations and messages are separate counts: distinct conversations, and messages.
• leadCount — Lead Ads leads the same ad produced, under the same number scope and date range. An ad that produced leads but never a conversation has no row here: read it from GET /v1/leads.
• Names: namesResolvedAt set with every name null means Pilot Status asked Meta and got nothing — usually the partner grant is missing. null means it has not asked yet.
• Privacy: lastHeadline and lastSourceUrl (the ad copy) are null for an ad seen only on a RELAY_ONLY number. The counts do not change. The report never carries conversation content.
• Cap: at most 200 ads, busiest first. truncated: true says the list was cut — narrow it with startDate/endDate.

​

Errors