Meta Conversions API (CAPI) Setup Guide

Implementation Options Compared

Choose your CAPI implementation based on your tech stack and resources:

GTM Server-Side (Recommended)

GTM Server-Side is the sweet spot for most B2B companies. It centralizes all tracking, handles deduplication automatically, and works with any form provider.

HubSpot Native CAPI

If HubSpot handles all your forms, enable native CAPI in Settings > Marketing > Ads > Meta integration. HubSpot automatically sends Lead events with full customer parameters.

Event Setup: What to Track

Map your key conversion points to Meta standard events:

Example CAPI Payload (Lead Event)

{
  "data": [{
    "event_name": "Lead",
    "event_time": 1713276000,
    "event_id": "lead_abc123_1713276000",
    "event_source_url": "https://yoursite.com/demo",
    "action_source": "website",
    "user_data": {
      "em": ["sha256_hashed_email"],
      "ph": ["sha256_hashed_phone"],
      "fn": ["sha256_hashed_firstname"],
      "ln": ["sha256_hashed_lastname"],
      "ct": ["sha256_hashed_city"],
      "st": ["sha256_hashed_state"],
      "zp": ["sha256_hashed_zip"],
      "country": ["sha256_hashed_country"],
      "external_id": ["your_crm_contact_id"],
      "client_ip_address": "192.168.1.1",
      "client_user_agent": "Mozilla/5.0...",
      "fbc": "fb.1.1713276000.AbCdEf",
      "fbp": "fb.1.1713276000.1234567890"
    },
    "custom_data": {
      "lead_source": "demo_request",
      "value": 500,
      "currency": "USD"
    }
  }],
  "access_token": "YOUR_ACCESS_TOKEN"
}

Deduplication Strategy

When running Pixel + CAPI together, you MUST deduplicate to avoid counting conversions twice.

How Deduplication Works

1. Generate a unique event_id when the conversion happens (client-side)
2. Pass the same event_id to both Pixel and CAPI
3. Meta matches events by event_name + event_id
4. If both arrive within 48 hours, Meta keeps only one (the first received)

Generating event_id

Use a deterministic ID when possible (e.g., transaction ID, form submission ID). Otherwise, generate a UUID on form submit:

// Generate event_id on form submit
const eventId = `lead_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;

// Push to dataLayer for GTM
dataLayer.push({
  'event': 'form_submit',
  'event_id': eventId,
  'user_email': userEmail  // For CAPI payload
});

// Fire Pixel with same event_id
fbq('track', 'Lead', {}, { eventID: eventId });

Verifying Deduplication

In Events Manager > Test Events, check the "Deduplication" column. You should see "Deduplicated" for events that arrived via both Pixel and CAPI.

Testing and Validation

Always test in Meta's Test Events tool before going live.

Test Mode Setup

1. Go to Events Manager > Your Pixel > Test Events
2. Copy your test_event_code
3. Add it to your CAPI payload: "test_event_code": "TEST12345"
4. Submit a test conversion on your site
5. Verify it appears in the Test Events tab

Validation Checklist

Event Match Quality (EMQ) Optimization

EMQ is Meta's 0-10 score measuring how well your events can be matched to Facebook users. Higher EMQ = better targeting and attribution.

Parameters That Improve EMQ

Hashing Requirements

• Use SHA256 for all PII (email, phone, names, location)
• Lowercase and trim whitespace BEFORE hashing
• Phone: remove special characters, include country code (e.g., 14155551234)
• IP address and user agent are NOT hashed

// Example: Hashing email in JavaScript
const crypto = require('crypto');
const email = '  John.Doe@Example.com  ';
const normalized = email.toLowerCase().trim();
const hashed = crypto.createHash('sha256').update(normalized).digest('hex');
// Result: e7b4c9f3a2...

Implementation Checklist

Use this checklist to ensure your CAPI implementation is complete:

Setup

• Generate CAPI access token in Events Manager
• Store token securely (environment variable, not client-side)
• Map conversion events to Meta standard events
• Choose implementation method (GTM SS, HubSpot, Direct)

Deduplication

• Generate event_id on conversion trigger
• Pass same event_id to Pixel AND CAPI
• Verify deduplication in Test Events

Event Quality

• Include hashed email on all events
• Include fbc and fbp cookies (pass from browser)
• Include external_id (CRM contact ID)
• Include client_ip_address and client_user_agent
• Verify EMQ score is 6+ in Events Manager

Validation

• Test with test_event_code in Test Events
• Verify events appear within seconds
• Confirm no API errors in response
• Remove test_event_code for production
• Monitor Event Match Quality over 7 days