Meta Ads CAPI Setup Guide

Meta Ads CAPI Setup Guide

Required Credentials

Token note: The System User access token (generated in Business Settings) is the primary credential for CAPI API calls. You still need a registered Meta App (App ID) to set up the CAPI integration in Events Manager — the App ID is required when creating the System User and configuring token permissions. Make sure the token includes these scopes: ads_management, business_management, pages_read_engagement.

---

When to Use

When setting up tracking for a new account, or when CPA shown in Meta Ads Manager is significantly higher than actual leads/​sales (indicating a tracking gap). CAPI is especially critical for lead generation campaigns where offline conversions are the true business outcome.

---

What CAPI Does (vs Pixel Only)

• Pixel only: Browser-based. Tracks users who click your ad and then take action on your website. Misses users who convert on different devices, after clearing cookies, or without clicking.
• CAPI: Server-to-server. Sends conversion events directly from your server to Meta. More accurate, more reliable, harder to block.

Together: Pixel + CAPI gives Meta the most complete picture → better optimization → lower CPA over time.

If you're not using CAPI, you're likely overpaying for every lead. The gap can be 20–50% depending on industry and browser mix.

---

Prerequisites

Before setting up CAPI, you need:

1. Meta Pixel installed on your website
2. A Meta App registered at developers.facebook.com (App ID required to configure CAPI in Events Manager)
3. A server environment that can send HTTP requests (or a partner integration like Shopify, WooCommerce, Zapier, or Google Tag Manager Server-side)
4. Access to your Meta Business Manager with pixel-level permissions

---

Step 1: Choose Your Integration Method

Recommended for Most SMBs — Native Platform Integration

Use your e-commerce platform's built-in Meta integration. This is the easiest path:

Steps (native integration):

1. Go to Meta Events Manager → select your Pixel
2. Click "About CAPI" → "Get Started"
3. Select your platform from the partner list
4. Follow the on-screen prompts to authorize the connection
5. Select which events to send (see Step 3 below)

---

Advanced — Manual Integration Options

Only use these if you are a developer or using a platform without native Meta integration.

For Direct API: use your META_ACCESS_TOKEN to send events to https://graph.facebook.com/​v21.0/​{pixel_id}/​events.

---

Step 2: Generate a System User Access Token

1. Go to Meta Business Manager → Business Settings → System Users
2. Create a new system user with "Analytics" or "Ads" permissions
3. Generate an access token with: ads_management, business_management, pages_read_engagement
4. Save this token securely — you'll need it for all API calls

---

Step 3: Configure Which Events to Send

1. Go to Meta Events Manager → select your Pixel
2. Click "About CAPI" → "Get Started"
3. Select your integration method
4. Configure which events to send:

---

Step 4: Test Your CAPI Connection

In Meta Events Manager:

1. Select your pixel → "Test Events" tab
2. Trigger the events on your website (submit a form, complete a purchase, etc.)
3. Check that events appear in the test panel within seconds

What to verify:

• Events are arriving with Deduping source confirmed (CAPI and Pixel aren't double-counted)
• Event IDs are being passed (for deduplication)
• Parameter completeness — more parameters = better optimization

Event parameters that improve CAPI quality:

• event_id — unique ID per event, enables deduplication
• user_data — email, phone, country (hashed with SHA-256)
• custom_data — value, currency, content_name, content_category

---

Step 5: Verify CAPI Is Working Correctly

In Meta Events Manager, check:

1. Event Quality Score — should be "Active" with green status
2. Matching Quality — how many user parameters Meta can match to real users
3. No significant gap between pixel events and CAPI events

Matching Quality benchmarks:

• 7+ parameters with good hash quality → Excellent
• 5–6 parameters → Good
• < 5 parameters → Poor — optimize your event setup

---

Step 6: Standard Events vs. Custom Events

Standard Events (Preferred)

Meta's predefined event names: Lead, Purchase, PageView, ViewContent, AddToCart, InitiateCheckout, CompleteRegistration. Better optimization because Meta knows exactly what the event means.

Custom Events

Use only when no standard event fits. Define custom name and parameters yourself. Required for: offline sales, phone calls, specific business workflows.

---

CAPI Common Issues and Fixes

---

Lead Generation — CAPI Is Especially Critical

For lead gen campaigns, the conversion happens offline — someone fills out a form, you call them, they sign up. Meta pixel can't see this.

What CAPI must send for lead gen:

1. Lead event when form is submitted (server-side, not just pixel)
2. Lead event when you mark a lead as qualified in your CRM (offline → Meta)
3. Revenue data if possible (even approximate) — helps Meta optimize for quality

CRM Integrations that support CAPI for leads: HubSpot, Salesforce, Zapier, Make.com.

If you're not sending offline lead data back to Meta: Meta is optimizing for form submissions only. You're paying for leads that never convert.

---

Event Deduplication — Preventing Double Counting

When both Pixel and CAPI send the same event (same event_id), Meta deduplicates automatically. Requirements:

• Same event_id in both pixel and CAPI call
• Same event_name
• Events fired within the same 48-hour window
• Same user data (at least one: email, phone, client_ip, client_user_agent)

---

Security Notes

• Access tokens for CAPI should be treated like passwords — store in environment variables, never in code repositories
• Use HTTPS for all CAPI calls
• Hash PII (email, phone) using SHA-256 before sending to Meta