Facebook (Meta) CAPI
The Facebook Conversions API (also known as Meta CAPI) is a server-side integration that sends event data directly from Chord CDP to Meta's servers. Unlike the Facebook Pixel (which runs in the browser), the Conversions API operates in cloud mode — events are sent server-to-server, making them immune to ad blockers and browser tracking restrictions.
Meta recommends using the Conversions API alongside the Facebook Pixel for maximum data coverage. When both are configured, Meta automatically deduplicates events using the event_id field.
Best Practices
- Use CAPI alongside the Meta Pixel — provides redundancy and better coverage
- Enable Automatic Advanced Matching — increases match quality without compromising privacy
- Send rich user data — the more hashed identifiers (email, phone, name, address) you provide, the higher your match rates
Expected Results
After enabling CAPI, you should see:
- Higher match rates in Meta Events Manager, as server-side events are not blocked by browsers
- Extended cookie lifespan for attribution, since fbc/fbp identifiers are sent server-side
Getting Started
This is a cloud-mode destination. You will need:
- Facebook Pixel ID — found in Meta Events Manager under your pixel settings
- Access Token — a system user token generated in Meta Business Settings. See Meta's documentation for instructions on generating a server-side access token
Connecting to the Facebook Conversions API CDP Destination
- Log into the Chord data platform.
- Navigate to the CDP.
- Click the "Add" button next to Destinations.
- Select Facebook Conversions API from the destination catalog.
- Enter the destination name, Pixel ID, and Access Token.
- Optionally configure:
- Action Source — defaults to website. Change to app, email, etc. if events originate from non-web sources
- Events filter — restrict which events are forwarded (empty sends all)
- Product Content ID Field — which product field to use as the content ID (sku, product_id, or variant_id). Defaults to sku. This value will be used in the contents.[].id field.
- Phone Field Name — the trait field containing phone numbers (leave empty to skip phone matching)
- Click "Create" to connect.
Events
Event Mapping
Chord Event | Facebook Event |
|---|---|
Page | PageView |
Checkout Started | InitiateCheckout |
Order Completed | Purchase |
Product Added | AddToCart |
Product Viewed | ViewContent |
Products Searched | Search |
Product Clicked | ViewContent |
Subscription Created | Subscribe |
(other track events) | Original event name passed through |
Page, track, and screen events are forwarded. Identify events are ignored.
Common Event Fields
These fields are included on every event sent to Meta.
Facebook Field | Chord Source (Priority Order) | Notes |
|---|---|---|
event_name | (mapped from event — see table above) | |
event_time | timestamp | Converted to Unix seconds |
event_id | messageId | Used for deduplication with the browser pixel |
action_source | Configured action source | Defaults to website |
event_source_url | context.page.url | |
User Data
All personally identifiable information (PII) is SHA256-hashed before being sent to Meta, in compliance with Meta's data processing requirements.
Facebook Field | Chord Source (Priority Order) | Notes |
|---|---|---|
em (email) | properties.email > context.traits.email | Lowercased and SHA256-hashed |
ph (phone) | properties.{phoneFieldName} > context.traits.{phoneFieldName} | Non-digits removed, leading zeros stripped, SHA256-hashed. Only sent if phone field name is configured |
fn (first name) | properties.first_name > first word of context.traits.name | SHA256-hashed |
ln (last name) | properties.last_name > second word of context.traits.name | SHA256-hashed |
zp (zip code) | properties.shipping_zipcode > context.traits.address.zipcode | SHA256-hashed |
ct (city) | properties.shipping_city > context.traits.address.city | SHA256-hashed; also enriched from server-side geo lookup |
country | properties.shipping_country > context.traits.address.country | SHA256-hashed; also enriched from geo lookup |
st (state) | (geo lookup) | SHA256-hashed region code from IP geolocation |
external_id | userId, anonymousId | Array of SHA256-hashed values |
client_ip_address | context.ip | Not hashed |
client_user_agent | context.userAgent | Not hashed |
fbc | properties.fbc > context.clientIds.fbc | Facebook click ID |
fbp | properties.fbp > context.clientIds.fbp | Facebook browser ID |
Custom Data (Track Events)
Track events include a custom_data block with the following structured schema fields. Additionally, any properties.* destination mappings configured in Hub that target non-schema fields are forwarded as custom properties alongside the structured fields.
Facebook Field | Chord Source (Priority Order) | Notes |
|---|---|---|
value | properties.total | String; defaults to "0" |
currency | properties.currency > properties.meta.i18n.currency | |
content_ids | Each product's sku > product_id > variant_id (or configured content ID field) | Array of product IDs |
contents | Array of { id, quantity, item_price } per product | quantity defaults to 1 |
content_type | (derived) | "product" for single product, "product_group" for multiple |
content_name | First product's name | |
content_category | First product's category | |
num_items | Count of products | |
When no properties.products array is present but properties.sku exists, a single content_ids entry is created from that SKU.
App Data (App Action Source Only)
When Action Source is set to app, an additional app_data block is included in the event payload. This is populated from context.app, context.os, context.device, and context.screen.
Field | Chord Source | Notes |
|---|---|---|
advertiser_tracking_enabled | (hardcoded) 0 | |
application_tracking_enabled | (hardcoded) 0 | |
extinfo[0] | context.os.name | "i2" for iOS/macOS, "a2" for Android |
extinfo[1] | context.app.namespace | App bundle ID |
extinfo[2] | context.app.version | App version string |
extinfo[4] | context.os.version | OS version |
extinfo[5] | context.device.model | Device model name |
extinfo[6] | context.locale | Device locale |
extinfo[9] | context.screen.width | Screen width in pixels |
extinfo[10] | context.screen.height | Screen height in pixels |
extinfo[11] | context.screen.density | Screen density |
extinfo[15] | context.timezone | Device timezone |
Custom Property Forwarding
Configure destination mappings in Hub with properties.* destination paths to forward additional event properties into custom_data. Only explicitly-configured non-schema fields are forwarded — nothing flows through automatically.
How to configure:
- Open the destination's Mappings tab in Hub.
- Add a mapping with source path properties.loyalty_tier and destination path properties.loyalty_tier.
- On the next event, custom_data.loyalty_tier will appear in the payload sent to Meta.
What is excluded:
- Schema fields already handled by the destination transform (e.g. currency, value, order_id, products) — these flow through the structured transform
- PII fields (email, phone, first_name, last_name) — these are handled via user_data with SHA-256 hashing
When a custom mapping targets a schema field (e.g. properties.value → properties.value), the customer-configured value overrides the destination's computed default. This allows schema fields to be sourced from a different event property — for example, mapping properties.total → properties.value to use your order total as the conversion value.
Testing and Validation
After connecting the destination:
- Use the Diagnostics tab in Meta Events Manager to confirm events are being received
- Use the Test Events tab to validate event payloads in real time
- Verify match rates — higher rates indicate user identifiers are being sent correctly
- Confirm revenue values and order counts align with your expectations
- Check the Facebook Developer Console for any API errors or authentication issues
If you are running both CAPI and the Facebook Pixel, ensure event_id values match across both to prevent duplicate counting. Chord CDP handles this automatically by using messageId as the event_id for both destinations.
Implementation Checklist
Task | Why It Matters |
|---|---|
Enable both CAPI and Pixel | Provides redundancy and better coverage |
Activate advanced matching | Increases match quality without compromising privacy |
Test events via Diagnostics + Test Events tab | Ensures proper delivery and deduplication |
Monitor developer console metrics | Proactively identifies API errors or auth issues |
Match event IDs across Pixel and server events | Prevents data duplication or mismatches |
Property Mappings
Use custom property mappings if the default field resolution does not match your data model:
Destination Path | Description |
|---|---|
properties.email | Email for user matching |
properties.total | Conversion value |
properties.currency | Currency code (e.g., USD) |
properties.products[].sku | Product content IDs |
properties.products[].price | Per-item price |
properties.products[].quantity | Per-item quantity |
Any destination path of the form properties.<field> that does not match a schema field listed above is treated as a custom property and promoted into custom_data. See Custom Property Forwarding.
Updated 27 May 2026