Sending Conversion Events to Meta via the API

This guide shows you how to build an unattended integration that uploads conversion events to Narrative and sends them to a Meta dataset (pixel) through Meta’s Conversions API. The examples send offline events, such as in-store purchases. Before you start, complete the prerequisites and set up API access. You need a profile ID and the numeric ID of the Meta dataset, which List your Meta datasets returns.

1. Create the dataset

A conversion-event dataset needs two columns:

meta_conversion_event, an object holding the event
at least one identifier Meta can match on, such as sha256_hashed_email

curl -X POST https://api.narrative.io/datasets \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "store_purchases_meta",
    "display_name": "Store Purchases (Meta)",
    "description": "Offline purchases for Meta",
    "write_mode": "append",
    "schema": {
      "file_config": { "type": "json", "normalize_field_names": false },
      "type": "object",
      "properties": {
        "meta_conversion_event": {
          "type": "object",
          "properties": {
            "meta_dataset_id": { "type": "long" },
            "event_id":        { "type": "string" },
            "event_name":      { "type": "string" },
            "event_timestamp": { "type": "timestamptz" },
            "source":          { "type": "string" },
            "custom_data": {
              "type": "object",
              "properties": {
                "value":    { "type": "double" },
                "currency": { "type": "string" },
                "order_id": { "type": "string" }
              }
            }
          }
        },
        "sha256_hashed_email": {
          "type": "object",
          "properties": { "value": { "type": "string" } }
        }
      }
    }
  }'

Every event needs meta_dataset_id, event_id, event_name, event_timestamp, and source. The meta_conversion_event attribute lists the optional fields, such as source_url, data_processing_options, more custom_data fields, and store_data. Add the ones you use to the schema before you activate it, because activation locks the schema. Record the id in the response, then activate the dataset:

curl -X POST https://api.narrative.io/datasets/{dataset_id}/activate \
  -H "Authorization: Bearer $NIO_API_TOKEN"

2. Confirm Meta accepts the dataset

curl -s "https://api.narrative.io/datasets/{dataset_id}/interfaces?tags=capi" \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"dataset_id": 12347, "accepted": [{"app_id": 8, "interface_id": "conversion_events"}], ...}

Look for "app_id": 8 with conversion_events in the accepted list. If it is missing, the dataset lacks one of the two columns from step 1.

3. Get a test event code

Send test events first, so you can watch them arrive before they count as real conversions:

Open the dataset in Events Manager

In Meta Events Manager, open the dataset you are sending to and choose Test events.

Choose the channel

Select the Offline channel and expand Confirm your server’s events are set up correctly.

Copy the code

Copy the test event code Meta shows, which starts with TEST. Keep the tab open while you test.

4. Create the connection

curl -X POST https://api.narrative.io/v2/connections \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "connections_dataset",
    "dataset_id": 12347,
    "profile_id": "<PROFILE_ID>",
    "quick_settings": {
      "type": "conversion_events",
      "test_event_code": "<TEST_EVENT_CODE>",
      "historical_data_enabled": true
    }
  }'
# → 201 {"type": "connections_dataset", "id": "<CONNECTION_ID>",
#        "app": {"id": 8, "name": "Facebook Connector"},
#        "quick_settings": {"type": "conversion_events", "test_event_code": "<TEST_EVENT_CODE>",
#                           "historical_data_enabled": true},
#        "status": "active", ...}

The connection names no Meta dataset. Each event names its own in meta_dataset_id, so one connection can send to every Meta dataset the profile can reach. historical_data_enabled set to true sends the events already in the dataset as well as new ones. Set it to false to send only events written after the connection exists.

5. Upload events

Each line of the file is one event. event_name takes the lowercase names listed in Event names, such as purchase. Offline events use physical_store as source.

{"meta_conversion_event": {"meta_dataset_id": <META_DATASET_ID>, "event_id": "order-1008", "event_name": "purchase", "event_timestamp": "2026-10-03T14:02:36Z", "source": "physical_store", "custom_data": {"value": 2.08, "currency": "USD", "order_id": "order-1008"}}, "sha256_hashed_email": {"value": "<SHA-256 of the trimmed, lowercased email>"}}

Upload and ingest the file the same way as an audience file (see Upload and ingest your file):

curl -X POST https://api.narrative.io/uploads/store-purchases.jsonl \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"path": "<UPLOAD_PATH>", "url": "https://...", "expiry": "..."}

curl -X PUT "<url from the response>" --upload-file ./store-purchases.jsonl

curl -X POST https://api.narrative.io/datasets/{dataset_id}/upload \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_file": "<UPLOAD_PATH>"}'

6. Check the events at Meta

Watch the Test events tab you left open. Within a few minutes each event appears with its event name (for example Purchase), status Processed, and Server as where it was received from. Expand an event to see its value, currency, order_id, action source, and the user data keys Meta matched on, such as Email. To hear about deliveries in your integration, subscribe to delivery notifications.

Going live

When the test events look right, send real conversions:

Create a connection on the dataset with the same request as step 4, leaving out test_event_code.
Delete the test connection with DELETE /v2/connections/{connection_id}.

Events sent through the new connection count as real conversions.

Keeping events flowing

Write new events to the dataset. The connection keeps running, so new rows reach Meta without further calls. Meta accepts offline events up to 90 days old and other events up to 7 days old. See Event age limits.

Stopping delivery

curl -X DELETE https://api.narrative.io/v2/connections/{connection_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → 200 {}

Deleting the connection archives it and stops further events from reaching Meta.

Troubleshooting

Symptom	Cause	Fix
`400 Dataset Schema Incompatible with Connector` with `required property 'meta_conversion_event' not found`	The dataset has no `meta_conversion_event` column	Create a new dataset with the schema in step 1

Getting help

Contact your Narrative relationship manager with your company ID, the dataset ID, and the failing request and response.

Delivering Custom Audiences via the API

Deliver hashed identifiers into a Custom Audience

Meta Conversions API Connector

Every meta_conversion_event field, event name, and action source

Connector Interfaces

Why a dataset connects to an interface rather than a connector

API Keys

Create and rotate keys for programmatic access

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Connector APIs

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

1. Create the dataset

2. Confirm Meta accepts the dataset

3. Get a test event code

4. Create the connection

5. Upload events

6. Check the events at Meta

Going live

Keeping events flowing

Stopping delivery

Troubleshooting

Getting help

Delivering Custom Audiences via the API

Meta Conversions API Connector

Connector Interfaces

API Keys

​1. Create the dataset

​2. Confirm Meta accepts the dataset

​3. Get a test event code

​4. Create the connection

​5. Upload events

​6. Check the events at Meta

​Going live

​Keeping events flowing

​Stopping delivery

​Troubleshooting

​Getting help

​Related content

Delivering Custom Audiences via the API

Meta Conversions API Connector

Connector Interfaces

API Keys

1. Create the dataset

2. Confirm Meta accepts the dataset

3. Get a test event code

4. Create the connection

5. Upload events

6. Check the events at Meta

Going live

Keeping events flowing

Stopping delivery

Troubleshooting

Getting help

Related content