What Is Meta CAPI?

Meta (formerly Facebook) is a global technology company that builds products and platforms to help people connect and share across its family of apps, including Facebook and Instagram. Its advertising ecosystem supports businesses in reaching targeted audiences through data-driven marketing tools.

Meta Conversions API (CAPI) is a server-side API that enables advertisers to send web and offline events directly from their servers to Meta. It complements or replaces pixel-based tracking by reducing browser limitations and supporting user privacy protections. It helps advertisers maintain conversion tracking, audience targeting, and optimization capabilities when client-side collection is limited.

Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Web, Mobile Web, and Mobile App
Event Scope: Full-Funnel Events

Capabilities

Sends server-side conversion and commerce lifecycle events to Meta Conversions API.
Supports optional Limited Data Use (LDU) default parameters for privacy processing.
Supports key matching and attribution identifiers via Facebook Tag ID sync (_fbp, _fbc).

Considerations

The Facebook Tag sync is required to populate fbc and fbp values in events.
Supports event batching (default batch size is 10; Meta accepts up to 1,000 events per batch, but rejects the entire batch if any event in the batch is invalid).
By default, this starter kit sends optional Limited Data Use (LDU) settings:
- data_processing_options = [LDU]
- data_processing_options_country = 0
- data_processing_options_state = 0
The default 0 values allow Meta to infer location automatically, which is commonly used when explicit location or consent logic is not available.
IP Address should be sent if state & country is not available to limit data use for persons in California.
The event_id and event_name parameters are used to deduplicate events.

Identity Sync

Sync Available: Yes
Required for Starter Kit: Highly recommended for user matching
Prerequisites: Pixel (Dataset) ID
Documentation: See Additional Facebook Tag Sync Documentation

Sync Details

The sync fires a match pixel using the Tag ID and hashed Match ID.
Explicit cookies _fbp and _fbc are set to persist identifiers for 90 days.
A sync completion marker (*_facebookTag_sync) is stored to suppress duplicate pixel fires.
Extra tag IDs, if provided, trigger additional pixels with unique sync markers.
Identifiers are added to server-side payloads for ad targeting and campaign measurement.

Starter Kit Setup Guide

1. Deploy the Facebook Tag Sync

To collect the required sync values (_fbp, _fbc), you must implement the Facebook Tag sync in your web pipeline. Refer to the Facebook Tag sync documentation to complete the setup. See Additional Facebook Tag Sync Documentation.

2. Gather Credentials

Finding your Pixel (Dataset) ID:
1. Go to Meta Events Manager
2. Go to Data Sources
3. Click on Pixel
4. Click on Settings to find Pixel ID (it can also appear as Dataset ID)
1. Generating an access token:
  1. Using Business Manager (recommended)
    1. Choose Pixel you want to implement
    2. Select the Settings Tab
    3. Find the Conversions API section and click on the Generate Access Token link under “Set up direct integration” and follow the instructions on the pop-up
      1. NOTE: Only visible to users with developer privileges for the business
    4. Save your access token in a secure place.
2. Ensuring Conversions API is enabled in your account
  1. Click on the Manage Integrations button in the Overview tab in Events Manager.
  2. In the pop-up screen, check if you have the Conversions API set up and active. If not, click on Add New Integration > Conversions API > Set up. There is no need to go through App Review or request any permissions.

3. Add a Meta CAPI Integration

From the integration library, add a Meta CAPI integration. Then, fill out the Connection Parameters:

Connection Parameter	Description
`API_VERSION`	Meta Graph API version (default: `v22.0`).
`PIXEL_ID`	Meta Pixel ID (may appear as Dataset ID).
`ACCESS_TOKEN`	Conversions API access token from Events Manager.

4. Configure Event Mapping

MetaRouter provides all of the event mappings that Meta CAPI integrations typically require. You may add custom events, parameters, or mappings in accordance with Meta’s API documentation.

5. Deploy to Pipeline

In the Pipelines tab, add your Meta CAPI integration.

Event Mappings

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output Key	Description	Expected Input
`action_source` Required	String: Identifies where the conversion occurred (for example, website or app).	Expression – Sets `'app'` for iOS/Android, defaults to `'website'`
`event_time` Required	Timestamp: Unix timestamp (seconds) when the actual event occurred.	Expression – Converts `timestamp` / `originalTimestamp` / `sentAt` to seconds since epoch
`event_source_url` Required	String: Website URL where the event occurred.	`context.page.url`
`event_id`	String: Unique ID used for deduplication when paired with `event_name`.	`messageId`
`user_data.em`	String: SHA256 hash of normalized email address.	Expression – SHA256 hash of `input.traits.email`
`user_data.client_ip_address` Required	String: Client IP address (do not hash).	`context.ip`
`user_data.client_user_agent` Required	String: Client browser user agent (do not hash).	`context.userAgent`
`user_data.external_id`	String: External identifier for the user (SHA256 hashing used in this kit).	`anonymousId` (then `sha256`)
`user_data.fbc`	String: Facebook click ID (do not hash).	`context.providers.facebookTag._fbc`
`user_data.fbp`	String: Facebook browser ID (do not hash).	`context.providers.facebookTag._fbp`
`data_processing_options`	Array: Data processing options for Limited Data Use (LDU).	Expression – Limited Data Usage returns `{ "LDU" }`
`data_processing_options_country`	Integer: Country code used with LDU processing.	Enrichment – `0`
`data_processing_options_state`	Integer: State code used with LDU processing.	Enrichment – `0`
`app_data.advertiser_tracking_enabled`	Boolean: Indicates whether advertiser tracking is enabled on the device.	`context.device.adTrackingEnabled`
`app_data.application_tracking_enabled`	Boolean: Indicates whether application tracking is enabled on the device.	`context.device.adTrackingEnabled`
`app_data.extinfo`	Array: Extended device and app information for app events.	Expression – Derived from `context` (app/os/device/screen/network/timezone)

Event Specific

Page

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'PageView'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the page associated with the event.	`properties.name`

Products Searched

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'Search'`
`custom_data.search_string`	String: Search query made by the user.	`properties.query`

Product Viewed

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'ViewContent'`
`custom_data.content_type`	String: Type of content.	Enrichment – Static value `'product'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	Array: Content IDs associated with the event.	Expression – Returns an array containing `properties.product_id`
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression – `price * (quantity or 1)`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression – Derived from `properties.product_id`, `properties.quantity`, `properties.price`

Product List Viewed

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'ViewContent'`
`custom_data.content_type`	String: Type of content.	Enrichment – Static value `'product'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the list associated with the event.	`properties.list_id`
`custom_data.content_ids`	Array: Content IDs associated with the event.	`properties.products` (pluck `product_id`)
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression – Sum of `price * (quantity or 1)` across `properties.products[]`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression – Derived from `properties.products[]`

Product Added

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'AddToCart'`
`custom_data.content_type`	String: Type of content.	Enrichment – Static value `'product'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	Array: Content IDs associated with the event.	Expression – Returns an array containing `properties.product_id`
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression – `price * (quantity or 1)`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression – Derived from `properties.product_id`, `properties.quantity`, `properties.price`

Cart Viewed

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'ViewContent'`
`custom_data.content_type`	String: Type of content.	Enrichment – Static value `'product'`
`custom_data.content_ids`	Array: Content IDs associated with the event.	`properties.products` (pluck `product_id`)
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression – Sum of `price * (quantity or 1)` across `properties.products[]`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression – Derived from `properties.products[]`

Checkout Started

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'InitiateCheckout'`
`custom_data.content_ids`	Array: Content IDs associated with the event.	`properties.products` (pluck `product_id`)
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression – Sum of `price * (quantity or 1)` across `properties.products[]`
`custom_data.num_items`	Integer: Total number of items in the checkout.	Expression – Sum of `(quantity or 1)` across `properties.products[]`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression – Derived from `properties.products[]`
`custom_data.order_id`	String: Unique order ID.	`properties.order_id`

Payment Info Entered

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'AddPaymentInfo'`
`custom_data.order_id`	String: Unique ID associated with the order.	`properties.order_id`
`custom_data.content_ids`	Object: Contains `checkout_id` and `order_id`.	Expression – Returns `{ checkout_id=properties.checkout_id, order_id=properties.order_id }`

Product Added To Wishlist

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'AddToWishlist'`
`custom_data.content_category`	String: The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	String: The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	String: Content ID associated with the event.	`properties.product_id`
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression – `price * (quantity or 1)`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression – Derived from `properties.product_id`, `properties.quantity`, `properties.price`

Order Completed

Output Key	Description	Expected Input
`event_name` Required	String: Facebook standard event name.	Enrichment – Static value `'Purchase'`
`custom_data.content_type`	String: Type of content.	Enrichment – Static value `'product'`
`custom_data.content_ids`	Array: Content IDs associated with the event.	`properties.products` (pluck `product_id`)
`custom_data.currency`	String: ISO 4217 currency code (defaults to USD).	`properties.currency` (uppercase, defaults to `'USD'`)
`custom_data.value`	Number: Total value for this event.	Expression – Sum of `price * (quantity or 1)` across `properties.products[]`
`custom_data.contents`	Array: Product objects with `id`, `quantity`, and `item_price`.	Expression – Derived from `properties.products[]`
`custom_data.order_id`	String: The order ID for this transaction as a string.	`properties.order_id`

Required & Recommended Identifiers

These identifiers must be mapped to Meta CAPI in order for successful user matching to occur. Without these IDs, any events sent to Meta CAPI may not be accurately reflected in reporting.

Attribute	Example	Sync Injector Required?
`client_user_agent` Required	`Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0`	No
`client_ip_address` Required	IPV4: `168.212.226.204` IPV6: `2001:0db8:85a3:0000:0000:8a2e:0370:7334`	No
`external_id` Recommended	`402DA762-201E-42C1-961B-C1fA6CBCF566`	No
`fbc` Highly Recommended	`fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890`	Yes
`fbp` Highly Recommended	`fb.1.1596403881668.1116446470`	Yes
`em` Recommended	`542d240129883c019e106e3b1b2d3f3cb3537c43c425364de8e951d5a3083345`	No

Integration Validation

Validate your Meta CAPI implementation by following Meta’s official verification steps in Events Manager:

Meta CAPI - Verifying Setup

Additional Meta CAPI Documentation