> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Meta Conversions API Connector
> Send conversion events to Meta for ad attribution and campaign optimization
The Meta Conversions API (CAPI) Connector sends conversion events from Narrative directly to Meta's Conversions API, improving Facebook and Instagram ad attribution and campaign performance.
## Overview
The connector routes conversion data — purchases, leads, checkouts, and more — from any dataset in Narrative to a Meta Ads dataset. Events are matched against Meta user accounts using hashed customer information, enabling Meta to attribute conversions back to ad campaigns and optimize delivery.
This connector supports:
* **Offline conversions** (e.g., in-store purchases, phone orders)
* **Online conversions** (e.g., website purchases, lead submissions)
* **App events**
Events are batched and delivered on a schedule you configure. PII fields are SHA-256 hashed before transmission in accordance with Meta's requirements.
## Prerequisites
* A **Meta Ads account** with an active dataset (formerly "pixel"). Your dataset ID is the numeric ID found in Meta Events Manager.
* A Narrative dataset containing the conversion data you want to send.
## Sending conversion events
Delivering conversion events to Meta involves three steps: creating a connector profile, preparing your dataset, and adding a connection.
### Step 1: Create a connector profile
In Narrative, go to **Connectors** and select **Meta Connector**.
Click **Connect** and sign in with your Meta account. During the OAuth flow, you will be prompted to:
1. **Select your business portfolio** — Choose the Meta business portfolio that owns the ad accounts you want to deliver events to.
2. **Grant ad account access** — Select the ad accounts that Narrative should be able to access. You must grant access to at least one ad account.
Make sure the ad accounts you select have an active dataset (pixel) configured in Meta Events Manager.
Choose the ad account where conversion events should be delivered.
### Step 2: Create your dataset
Your dataset must be mapped to the [`meta_conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/meta_conversion_event) Rosetta Stone attribute. The recommended approach is to map your source data to this attribute and then materialize it using Data Studio or NQL.
The connector profile requires your dataset to include `meta_conversion_event` **and** at least one [supported user identifier](#supported-user-identifiers) for user matching. Meta uses these identifiers to match conversion events to user accounts. Any dataset that contains the required attributes in the correct schema is eligible for delivery.
See the [attribute schema](#the-meta_conversion_event-attribute) below for the full list of event fields, and [Supported user identifiers](#supported-user-identifiers) for the identity attributes your dataset must include.
### Step 3: Add a connection
Navigate to the Meta connector profile you created in Step 1.
Click **Add Connection** and select **Deliver Conversion Events** as the connection type.
* **Deliver all data** — Toggle on to deliver all data currently in the dataset. If off, only new data written after the connection is created will be delivered.
* **Test Event Code** *(optional)* — Enter a test event code from Meta Events Manager. When provided, events are sent as test events and appear in Meta's **Test Events** tab instead of being processed as real conversions. Use this to validate your setup before going live.
Click **Connect** to activate. Events will begin delivering on the next scheduled run.
## The `meta_conversion_event` attribute
The [`meta_conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/meta_conversion_event) attribute is Narrative's standardized Rosetta Stone schema for conversion events sent to Meta. When you map your dataset columns to this attribute, Narrative handles transformation, hashing, batching, and delivery to Meta's API.
### Top-level fields
| Narrative Field | Meta CAPI Field | Type | Required | Description |
| --------------------------------- | --------------------------------- | --------------- | -------- | --------------------------------------------------------------------------------------- |
| `meta_dataset_id` | *(routing)* | `long` | **Yes** | The Meta Ads dataset/pixel ID to deliver events to. |
| `event_id` | `event_id` | `string` | **Yes** | Unique string for deduplication. Use an order number, transaction ID, or random string. |
| `event_name` | `event_name` | `string` (enum) | **Yes** | The type of conversion event. See [Event names](#event-names). |
| `event_timestamp` | `event_time` | `timestamptz` | **Yes** | Timestamp when the event occurred. |
| `source` | `action_source` | `string` (enum) | **Yes** | Where the conversion occurred. See [Action sources](#action-sources). |
| `source_url` | `event_source_url` | `string` | No | The browser URL where the event occurred. Required for `website` events. |
| `opt_out` | `opt_out` | `boolean` | No | If `true`, the event is used for attribution only, not delivery optimization. |
| `data_processing_options` | `data_processing_options` | `string[]` | No | Use `["LDU"]` to enable Limited Data Use for non-consented users. |
| `data_processing_options_country` | `data_processing_options_country` | `long` | No | Required if LDU is set. `1` = USA, `0` = geolocate. |
| `data_processing_options_state` | `data_processing_options_state` | `long` | No | Required if LDU is set without an IP address. `1000` = California, `0` = geolocate. |
### Custom data fields
Additional event data used by Meta for attribution and optimization. Some fields are required depending on event type.
| Narrative Field | Meta CAPI Field | Type | Required For | Description |
| ------------------------------- | ------------------------------- | ---------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `custom_data.value` | `custom_data.value` | `double` | `purchase` | Monetary value of the conversion |
| `custom_data.currency` | `custom_data.currency` | `string` | `purchase` | ISO 4217 currency code (e.g., `USD`) |
| `custom_data.order_id` | `custom_data.order_id` | `string` | Offline events | Transaction or order ID for offline event deduplication |
| `custom_data.predicted_ltv` | `custom_data.predicted_ltv` | `double` | — | Predicted lifetime value of the conversion |
| `custom_data.content_ids` | `custom_data.content_ids` | `string[]` | — | Product SKUs or content IDs |
| `custom_data.content_type` | `custom_data.content_type` | `string` | — | `product` or `product_group` |
| `custom_data.contents` | `custom_data.contents` | `object[]` | — | Array of product objects. Each requires `id` (string) and `quantity` (long). Optional: `item_price` (double), `delivery_category` (`curbside`, `home_delivery`, `in_store`) |
| `custom_data.num_items` | `custom_data.num_items` | `long` | — | Number of items. Use only with `initiate_checkout` |
| `custom_data.search_string` | `custom_data.search_string` | `string` | — | Search query. Use only with `search` events |
| `custom_data.delivery_category` | `custom_data.delivery_category` | `string` | — | Delivery type for purchase events: `curbside`, `home_delivery`, or `in_store` |
| `custom_data.item_number` | `custom_data.item_number` | `string` | — | Identifier to distinguish multiple events within the same order |
### Store data fields
For physical store conversions only.
| Narrative Field | Meta CAPI Field | Type | Description |
| -------------------------- | -------------------------- | -------- | -------------------------------------------------------- |
| `store_data.brand_page_id` | `store_data.brand_page_id` | `long` | Facebook Page ID of the brand |
| `store_data.store_code` | `store_data.store_code` | `string` | Unique alphanumeric store identifier (max 64 characters) |
| `store_data.store_page_id` | `store_data.store_page_id` | `long` | Facebook Page ID of the store |
***
## Supported user identifiers
In addition to the `meta_conversion_event` attribute, your dataset must include at least one of the following Rosetta Stone identifier attributes. Meta uses these to match conversion events to user accounts. All PII values are SHA-256 hashed by Narrative before transmission.
Providing more identifier types improves Meta's match quality.
| Identifier Attribute | Description |
| ------------------------------------------------------- | -------------------------------------------------------------------- |
| `sha256_hashed_email` | SHA-256 hashed email address |
| `hashed_email` | Hashed email address (any supported hash) |
| `e164_phone_number` | Phone number in E.164 format |
| `telephone_number` | Phone number |
| `person_name` + `iso_3166_1_country` + `postal_address` | Full name, country, and postal address (all three required together) |
| `android_advertising_id` | Android advertising ID (GAID) |
| `apple_idfa` | Apple Identifier for Advertisers (IDFA) |
| `mobile_id_unique_identifier` | Mobile advertising ID |
| `unique_id` | Any unique user identifier |
| `narrative_id` | Narrative platform identity |
***
## Reference
### Event names
The `event_name` field accepts the following values. Custom event names are not supported.
| Value | Meta Standard Event |
| ----------------------- | -------------------- |
| `add_payment_info` | AddPaymentInfo |
| `add_to_cart` | AddToCart |
| `add_to_wishlist` | AddToWishlist |
| `complete_registration` | CompleteRegistration |
| `contact` | Contact |
| `customize_product` | CustomizeProduct |
| `donate` | Donate |
| `find_location` | FindLocation |
| `initiate_checkout` | InitiateCheckout |
| `lead` | Lead |
| `other` | Other |
| `purchase` | Purchase |
| `schedule` | Schedule |
| `search` | Search |
| `start_trial` | StartTrial |
| `submit_application` | SubmitApplication |
| `subscribe` | Subscribe |
| `view_content` | ViewContent |
### Action sources
| Value | Use When |
| -------------------- | ------------------------------------------------------------------------------------ |
| `physical_store` | Conversion happened in a brick-and-mortar location. Required for all offline events. |
| `website` | Conversion happened on a website. Requires `source_url`. |
| `app` | Conversion happened in a mobile app. |
| `email` | Conversion originated from an email campaign. |
| `phone_call` | Conversion happened over the phone. |
| `chat` | Conversion happened via chat. |
| `business_messaging` | Conversion via business messaging (e.g., WhatsApp). |
| `system_generated` | Automated or system-generated event. |
| `other` | Any other source. |
### Event age limits
Meta enforces limits on how old events can be when received:
* **Offline events** (`physical_store`): up to **90 days** old
* **All other event types**: must be **less than 7 days** old
Events outside these windows will be rejected by Meta.
### Deduplication
Meta uses `custom_data.order_id` to deduplicate offline conversion events. For web and app events, `event_id` is used. Ensure these values are stable and consistent if you are sending the same events from multiple sources (e.g., both a pixel and CAPI).
***
## Data privacy
Narrative hashes all customer information fields (email, phone, name, etc.) using SHA-256 before transmission. Raw PII is never sent to Meta.
For users who have not consented to data sharing, set `data_processing_options` to `["LDU"]` and provide the appropriate `data_processing_options_country` and `data_processing_options_state` values to enable Meta's [Limited Data Use](https://developers.facebook.com/docs/marketing-api/overview/data-processing-options) mode.
***
## Related content
Deliver audience data to Facebook and Instagram advertising
Understand how connectors deliver data
Prepare identifiers for delivery