Meta CAPI
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:
- Go to Meta Events Manager
- Go to Data Sources
- Click on Pixel
- Click on Settings to find Pixel ID (it can also appear as Dataset ID)
-
Generating an access token:
-
Using Business Manager (recommended)
-
Choose Pixel you want to implement
-
Select the Settings Tab
-
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
- NOTE: Only visible to users with developer privileges for the business
-
Save your access token in a secure place.
-
-
-
Ensuring Conversions API is enabled in your account
- Click on the Manage Integrations button in the Overview tab in Events Manager.
- 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:
- Consent Type: This should align to your Facebook categorization within your Consent Management tool. Refer to the Advanced Consent Enforcement documentation for more information.
- Tag ID: Include your Pixel ID here.
- Extra Tag IDs: Extra Pixel IDs can be included here.
- 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 |
---|---|---|
| Type: string | Expression: Sets |
| Type: timestamp | N/A - Expression |
| Type: string |
|
| Type: string |
|
| Type: string |
|
| Type: string |
|
| Type: string |
|
| Type: string |
|
| Type: string |
|
| Type: string |
|
| Type: string |
|
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 |
---|---|---|
| Type: string | N/A: Enriched Value |
| Type: string |
|
| Type: string |
|
products_searched
Output Key | Description | Expected Input |
---|---|---|
| Type: string | N/A: Enriched Value |
| Type: string |
|
product_viewed
Output Key | Description | Expected Input |
---|---|---|
| Type: string | N/A: Enriched Value |
| Type: string | N/A: Enriched Value |
| Type: string |
|
| Type: string |
|
| Type: array of integers or strings |
|
| Type: string |
|
| Type: string |
|
| Type: integer or float |
|
| Type: array of objects |
|
| Type: array of objects |
|
| Type: string |
|
product_list_viewed
Output Key | Description | Expected Input |
---|---|---|
| Type: string | N/A: Enriched Value |
| Type: string | N/A: Enriched Value |
| Type: string |
|
| Type: string |
|
| Type: array of integers or strings |
|
| Type: string |
|
| Type: integer or float |
|
| Type: string |
|
| Type: integer or float |
|
| Type: array of objects |
|
| Type: integer or float |
|
| Type: string |
|
product_added
Output Key | Description | Expected Input |
---|---|---|
| Type: string | N/A: Enriched Value |
| Type: string | N/A: Enriched Value |
| Type: string |
|
| Type: string |
|
| Type: array of integers or strings |
|
| Type: string |
|
| Type: string |
|
| Type: integer or float |
|
| Type: array of objects |
|
| Type: integer or float |
|
| Type: string |
|
cart_viewed
Output Key | Description | Expected Input |
---|---|---|
| Type: string | N/A: Enriched Value |
| Type: string | N/A: Enriched Value |
| Type: array of integers or strings |
|
| Type: string |
|
| Type: string |
|
| Type: integer or float |
|
| Type: array of objects |
|
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 |
---|---|---|
| Type: string | N/A: Enriched Value |
| Type: string | N/A: Enriched Value |
| Type: array of integers or strings |
|
| Type: string |
|
| Type: string |
|
| Type: integer or float |
|
| Type: array of objects |
|
| Type: integer or float |
|
| Type: string |
|
| Type: string |
|
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? |
---|---|---|
|
| No |
| IPV4: | No |
|
| Yes |
|
| Yes |
|
| 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 |
---|---|---|
| Lowercase SHA256 hash of normalized email. Trim any leading and trailing spaces. Convert all characters to lowercase. | Before hashing: |
| Hashing required. Remove symbols, letters, and any leading zeros. Phone numbers must include a country code to be used for matching. | Before normalisation: |
| 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: |
| 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: |
| 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: |
| 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: |
| 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: |
| 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: |
| Gender hashed in SHA256 format. We accept gender in the form of an initial in lowercase. | Before normalisation: |
| 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: |
| Do not hash. Your install ID. This field represents unique application installation instances. | Firebase Installation ID or FID for Android or IDFV for iOS |
| 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: |
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
Updated 13 days ago