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. The company focuses on social networking, digital advertising, virtual and augmented reality, and AI-driven innovation. Its advertising ecosystem supports businesses in reaching targeted audiences through advanced 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 improving data accuracy, reducing browser limitations, and enhancing user privacy. CAPI helps advertisers maintain conversion tracking, audience targeting, and optimization capabilities even when client-side data collection is limited.

Meta CAPI Key Features

Enables Meta Pixel removal
Up to 30% more data- including conversions- tracked compared to the Meta Pixel
All customer data events and attributes unlocked for custom event mapping and transformation
No effect on website load latency

Getting Started - From Your Meta Business Account

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)
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.
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.

Getting Started - From Your MetaRouter Account

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`	API version for integration. Latest version is `v22.0`.
`PIXEL_ID`	ID of Facebook Pixel
`ACCESS_TOKEN`	Access token generated for API

Add a Facebook Tag sync

Adding the Facebook Tag sync is required to include the fbc and fbp values within your event stream. To do this:

From the Pipelines page, find the pipeline associated with the web property you’d like to add a sync to. Hover over the three dot dropdown and select the “Build AJS File” option.
Scroll down to the Identity Syncs section, click the Select Identity Syncs dropdown, and select Facebook Tag.
Fill out the following fields:
1. Consent Type: This should align to your Facebook categorization within your Consent Management tool. Refer to the Advanced Consent Enforcement documentation for more information.
2. Tag ID: Include your Pixel ID here.
3. Extra Tag IDs: Extra Pixel IDs can be included here.
4. Fire on Re-Sync. This will fire a Facebook sync whenever an Identify call is made.
When you are finished configuring your AJS file, scroll down and click Save and Build File.
Deploy your file to see the changes applied to your web property.

Event Mappings

MetaRouter provides all of the event mappings that Meta integrations typically require, including e-commerce lifecycle events. You may add custom events, parameters or mappings in accordance with Meta's API documentation.

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	Type: string This field allows you to specify where your conversions occurred.	Expression: Sets `action_source` to `'app'` for iOS/Android devices; defaults to `'website'` for all other device types.
`event_time`	Type: timestamp A Unix timestamp in seconds indicating when the actual event occurred.	N/A: Enriched Value
`user_data.em`	Type: string Lowercase SHA256 hash of normalized email. Trim any leading and trailing spaces. Convert all characters to lowercase.	`input.context.traits.email`
`event_id`	Type: string A unique string. The event_id and event_name parameters are used to deduplicate events.	`messageId`
`event_source_url` Required	Type: string The browser URL where the event happened. The URL must begin with http:// or https:// and should match the verified domain.	`context.page.url`
`user_data.client_ip_address` Required	Type: string Do not hash. IP address.	`context.ip`
`user_data.client_user_agent` Required	Type: string Do not hash. User agent.	`context.userAgent`
`user_data.external_id`	Type: string Anonymous 1st party cookie.	`anonymousId`
`user_data.fbc`	Type: string Do not hash. Facebook click ID.	`context.providers.facebookTag._fbc`
`user_data.fbp`	Type: string Do not hash. Facebook cookie.	`context.providers.facebookTag._fbp`
`event.xdm.identityMap.FPID`	Type: string	`anonymousId`

Event Specific

The following event mappings assume that you have named your events according to the MetaRouter AJS spec. If you have implemented custom events, or event parameters do not match the Expected Inputs, you will need to overwrite the provided information your own.

page

Output Key	Description	Expected Input
`event_name`	Type: string A standard event or custom event name. Used to deduplicate events.	N/A: Enriched Value
`custom_data.content_category`	Type: string The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	Type: string The name of the page or product associated with the event.	`properties.name`

products_searched

Output Key	Description	Expected Input
`event_name`	Type: string A standard event or custom event name. Used to deduplicate events.	N/A: Enriched Value
`customer_data.search_string`	Type: string Use only with Search events. A search query made by a user.	`properties.query`

product_viewed

Output Key	Description	Expected Input
`event_name`	Type: string A standard event or custom event name. Used to deduplicate events.	N/A: Enriched Value
`custom_data.content_type`	Type: string Should be set to product or product_group.	N/A: Enriched Value
`custom_data.content_category`	Type: string The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	Type: string The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	Type: array of integers or strings The content IDs associated with the event, such as product SKUs for items in an AddToCart event.	`properties.product_id`
`custom_data.currency`	Type: string The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.	`properties.currency`
`custom_data.value`	Type: string A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`properties.price`
`custom_data.value`	Type: integer or float A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`properties.quantity`
`custom_data.contents`	Type: array of objects A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.product_id`
`custom_data.contents`	Type: array of objects A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.quantity`
`custom_data.contents`	Type: string A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.price`

product_list_viewed

Output Key	Description	Expected Input
`event_name`	Type: string A standard event or custom event name. Used to deduplicate events.	N/A: Enriched Value
`custom_data.content_type`	Type: string Should be set to product or product_group.	N/A: Enriched Value
`custom_data.content_category`	Type: string The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	Type: string The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	Type: array of integers or strings The content IDs associated with the event, such as product SKUs for items in an AddToCart event.	`properties.product_id`
`custom_data.currency`	Type: string The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.	`properties.currency`
`custom_data.value`	Type: integer or float A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`properties.products`
`custom_data.value`	Type: string A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`properties.price`
`custom_data.value`	Type: integer or float A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`properties.quantity`
`custom_data.contents`	Type: array of objects A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.product_id`
`custom_data.contents`	Type: integer or float A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.quantity`
`custom_data.contents`	Type: string A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.price`

product_added

Output Key	Description	Expected Input
`event_name`	Type: string A standard event or custom event name. Used to deduplicate events.	N/A: Enriched Value
`custom_data.content_type`	Type: string Should be set to product or product_group.	N/A: Enriched Value
`custom_data.content_category`	Type: string The category of the content associated with the event.	`properties.category`
`custom_data.content_name`	Type: string The name of the page or product associated with the event.	`properties.name`
`custom_data.content_ids`	Type: array of integers or strings The content IDs associated with the event, such as product SKUs for items in an AddToCart event.	`properties.product_id`
`custom_data.currency`	Type: string The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.	`properties.currency`
`custom_data.value`	Type: string A numeric value associated with this event. This could be a monetary value or a value in some other metric ._	`properties.price`
`custom_data.value`	Type: integer or float A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`properties.quantity`
`custom_data.contents`	Type: array of objects A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.product_id`
`custom_data.contents`	Type: integer or float A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.quantity`
`custom_data.contents`	Type: string A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.price`

cart_viewed

Output Key	Description	Expected Input
`event_name`	Type: string A standard event or custom event name.	N/A: Enriched Value
`custom_data.content_type`	Type: string Should be set to product or product_group.	N/A: Enriched Value
`custom_data.content_ids`	Type: array of integers or strings The content IDs associated with the event, such as product SKUs for items in an AddToCart event.	`properties.products`
`custom_data.currency`	Type: string The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.	`properties.currency`
`custom_data.value`	Type: string A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`properties.price`
`custom_data.value`	Type: integer or float A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`input.properties.quantity`
`custom_data.contents`	Type: array of objects A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.products`

product_added_to_wishlist

Output Key	Description	Expected Input
`event_name`	String: Facebook standard event name.	Enrichment – Static value `"AddToWishlist"`
`custom_data.content_category`	String: Product category.	`properties.category`
`custom_data.content_name`	String: Product name.	`properties.name`
`custom_data.content_ids`	String: ID of the product added to wishlist.	`properties.product_id`
`custom_data.currency`	String: ISO currency code (e.g., "USD").	`properties.currency` (uppercase, defaults to `"USD"`)
`custom_data.value`	Float: Total value of the wishlisted item(s).	Expression – `price * quantity`
`custom_data.contents`	Array: Array of product objects with `id`, `quantity`, and `item_price`.	Derived from `input.properties`

checkout_started

Output Key	Description	Expected Input
`event_name`	String: Facebook standard event name.	Enrichment – Static value `"InitiateCheckout"`
`custom_data.content_ids`	Array: List of product IDs being purchased.	Plucked from `properties.products[].product_id`
`custom_data.currency`	String: ISO currency code.	`properties.currency` (uppercase, defaults to `"USD"`)
`custom_data.value`	Float: Total order value.	Expression – Sum of `price * quantity`
`custom_data.num_items`	Integer: Number of items in the checkout.	Expression – Sum of `quantity` from all products
`custom_data.contents`	Array: List of product objects with `id`, `quantity`, and `item_price`.	Derived from `input.properties.products`
`custom_data.order_id`	String: Unique order ID.	`properties.order_id`

payment_info_entered

Output Key	Description	Expected Input
`event_name`	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`	Array: List of related checkout and order identifiers.	Expression – Combines `checkout_id` and `order_id` into an array

order_completed

Output Key	Description	Expected Input
`event_name`	Type: string A standard event or custom event name.	N/A: Enriched Value
`custom_data.content_type`	Type: string Should be set to product or product_group.	N/A: Enriched Value
`custom_data.content_ids`	Type: array of integers or strings The content IDs associated with the event, such as product SKUs for items in an AddToCart event.	`properties.product_id`
`custom_data.currency`	Type: string The currency for the value specified, if applicable. Currency must be a valid ISO 4217 three-digit currency code. Default USD.	`properties.currency`
`custom_data.value`	Type: string A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`properties.price`
`custom_data.value`	Type: integer or float A numeric value associated with this event. This could be a monetary value or a value in some other metric .	`input.properties.quantity`
`custom_data.contents`	Type: array of objects A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.product_id`
`custom_data.contents`	Type: integer or float A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.quantity`
`custom_data.contents`	Type: string A list of JSON objects that contain the product IDs associated with the event plus information about the products.	`properties.price`
`custom_data.order_id`	Type: string The order ID for this transaction as a string.	`properties.order_id`

Required & Recommended Identifiers

These identifiers must be mapped to Meta in order for successful user matching to occur. Without these IDs, any events sent to Meta Conversions API will be rejected. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.

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`	Yes
`fbc` Recommended	`fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890`	Yes
`fbp` Recommended	`fb.1.1596403881668.1116446470`	Yes

*Required for web events

**IP Address should be sent if state & country is not available to "limit data use" for persons in California

Additional Identifiers

These identifiers should be mapped to Meta whenever possible to ensure the highest user match rates possible. If using these identifiers, they must be added as Global or Event Specific mappings.

Attribute	Description	Example
`em`	Lowercase SHA256 hash of normalized email. Trim any leading and trailing spaces. Convert all characters to lowercase.	Before hashing: `[email protected]` After hashing: `542d240129883c019e106e3b1b2d3f3cb3537c43c425364de8e951d5a3083345`
`ph`	Hashing required. Remove symbols, letters, and any leading zeros. Phone numbers must include a country code to be used for matching.	Before normalisation: `+44 844 412 4653` After normalisation: `448444124653` After SHA-256 hash: `dc008fda46e2e64002cf2f82a4906236282d431c4f75e5b60bfe79fc48546383`
`fn`	First name hashed in SHA256 format. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation. If using special characters, the text must be encoded in UTF-8 format.	Before normalisation: `Jerry` After normalisation: `jerry` After SHA-256 hash: `3a5a2512949399115565867a73a413ec6ba215c8f2df385f78b33238a6639b7c`
`ln`	Last name hashed in SHA256 format. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation. If using special characters, the text must be encoded in UTF-8 format.	Before normalisation: `Seinfeld` After normalisation: `seinfeld` After SHA-256 hash: `0c957e9f09a2444a8868737bf42b16f40d4e3533b57dc31a61124c2cd1bae31b`
`ct`	City hashed in SHA256 format. Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation, no special characters, and no spaces. If using special characters, the text must be encoded in UTF-8 format.	Before normalisation: `Beverly Hills` After normalisation: `beverlyhills` After SHA-256 hash: `6195198aeec54576f52474bf92cb02ec1c5e117d1dd9ddbceb08f5bfc545a0b8`
`st`	State hashed in SHA256 format. Use the 2-character ANSI abbreviation code in lowercase. Normalize states outside the U.S. in lowercase with no punctuation, no special characters, and no spaces.	Before normalisation: `California` After normalisation: `ca` After SHA-256 hash: `6959097001d10501ac7d54c0bdb8db61420f658f2922cc26e46d536119a31126`
`zp`	Zip Code hashed in SHA256 format. Use lowercase with no spaces and no dash. Use only the first 5 digits for U.S. zip codes. Use the area, district, and sector format for the UK.	Before normalisation: `90210-1002` After normalisation: `90210` After SHA-256 hash: `b83c588da0c6931625f42e0948054a3ade722bfd02c27816305742ed7390ac6c`
`db`	Date of Birth hashed in SHA256 format. MetaRouter accepts the YYYYMMDD format accommodating a range of month, day and year combinations, with or without punctuation.	Before normalisation: `4/29/1954` After normalisation: `19540429` After SHA-256 hash: `8704e3f1c5795aacf516e43c24a3914d657be55c2d643523fdb233a9d094237c`
`ge`	Gender hashed in SHA256 format. We accept gender in the form of an initial in lowercase.	Before normalisation: `MALE` After normalisation: `m` After SHA-256 hash: `62c66a7a5dd70c3146618063c344e531e6d4b59e379808443ce962b3abd63c5a`
`country`	Country hashed in SHA256 format. Use the lowercase, 2-letter country codes in ISO 3166-1 alpha-2. Always include your customers' countries’ even if all of your country codes are from the same country.	Before normalisation: `United States` After normalisation: `us` After SHA-256 hash: `79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621`
`anon_id`	Do not hash. Your install ID. This field represents unique application installation instances.	Firebase Installation ID or FID for Android or IDFV for iOS
`madid`	Do not hash. Your mobile advertiser ID, the advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device.	GAID for Android: `385c7219-aceb-4f78-8946-738b568e0590` IDFA for iOS: `6D92078A-8246-4BA4-AE5B-76104861E7DC`

Additional Meta Conversions API Documentation

https://developers.facebook.com/docs/marketing-api/conversions-api/best-practices/
https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event#event-id