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" } }
        }
      }
    }
  }'

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"

Required columns

The meta_conversion_event column is an object. These properties are required in every event:

Property	Type
`meta_dataset_id`	`long`
`event_id`	`string`
`event_name`	`string`
`event_timestamp`	`timestamptz`
`source`	`string`

The optional properties are source_url, opt_out, data_processing_options, data_processing_options_country, data_processing_options_state, custom_data, and store_data. The meta_conversion_event attribute gives the type of each one and the fields inside custom_data and store_data. Add the ones you use to the schema before you activate it, because activation locks the schema. The dataset also needs at least one of these identifier columns:

Column	Shape of each value
`sha256_hashed_email`	`{"value": ...}`
`hashed_email`	`{"value": ..., "type": "..."}`
`sha256_hashed_phone_number`	`{"value": ...}`
`e164_phone_number`	A string
`telephone_number`	A string
`apple_idfa`	`{"value": ...}`
`android_advertising_id`	`{"value": ...}`
`mobile_id_unique_identifier`	`{"value": ..., "type": "..."}`
`unique_id`	`{"value": ..., "type": "..."}`
`narrative_id`	`{"context": "...", "value": ...}`
`person_name`, `iso_3166_1_country`, and `postal_address`, together	`person_name` is `{"given_name": "...", "family_name": "..."}`, `iso_3166_1_country` is a string, and `postal_address` is `{"postal_code": "..."}`

Each identifier column is named after its Rosetta Stone attribute, and the connector matches on that column name. A column holds either a plain string or an object. In the dataset schema, declare a string column with "type": "string", and declare an object column with "type": "object" and its properties:

{
  "type": "object",
  "properties": {
    "<string_attribute>": { "type": "string" },
    "<object_attribute>": {
      "type": "object",
      "properties": { "<property>": { "type": "<type>" } }
    }
  }
}

Send an object column as an object in each row:

{"<string_attribute>": "...", "<object_attribute>": {"<property>": "..."}}

See your connector’s reference page for the attributes it accepts and their exact shapes. A row with the required properties and one identifier looks like this:

{"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"}, "sha256_hashed_email": {"value": "<SHA-256 of the trimmed, lowercased email>"}}

2. Confirm Meta accepts the dataset

Before you create a connection, ask Narrative which connector interfaces the dataset satisfies:

curl -s https://api.narrative.io/datasets/{dataset_id}/interfaces \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"dataset_id": 12345,
#    "accepted": [{"app_id": <APP_ID>, "interface_id": "<INTERFACE_ID>"}, ...],
#    "errors": [{"app_id": <APP_ID>, "interface_id": "<INTERFACE_ID>", "details": {...}}, ...]}

The response checks the dataset’s schema against every interface of the connectors your company has installed, and sorts the results into two lists:

accepted lists each interface you can connect the dataset to, by the connector’s app_id and the interface_id.
errors lists each interface the schema does not satisfy. Its details hold the reason, such as "required property '<column>' not found".

Add ?tags=<tag> to check only the interfaces that carry that tag. When the interface you want is under errors, the dataset’s schema doesn’t meet what the interface needs, for example a missing column or property. Activation locks the schema, so create a new dataset that fixes what the error names. For Meta conversion events, add ?tags=capi and look for "app_id": 8 with conversion_events in accepted:

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"}], ...}

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. What the connection does describes test_event_code, historical_data_enabled, and their defaults.

5. Upload events

Each line of the file is one event, in a row that matches the schema you declared in step 1. event_name takes the lowercase names listed in Event names, such as purchase. Offline events use physical_store as source. For the columns Meta accepts and their shapes, see The meta_conversion_event attribute, Supported user identifiers, and Required columns. You can load a file into a dataset over the API in two ways:

Signed-URL upload. Your integration uploads one file of up to 3 GB, then asks Narrative to ingest it.
Managed S3 bucket. You write files to an S3 bucket that Narrative manages, and Narrative ingests each batch on its own. Use a managed bucket for files larger than 3 GB, or for files that another system delivers on a schedule.

Choose a file format

The dataset’s file_config.type sets the format of every file you load into it. Parquet and JSON Lines both hold object columns, which nest properties inside one column:

Parquet (parquet) is the most compatible format for connector datasets. It stores nested struct columns and their types natively, and Narrative matches columns to the schema by name at every level.
JSON Lines (json) holds one JSON object per line. Narrative matches each nested object to the schema by name.

CSV datasets (flat) hold only scalar columns, so they can’t carry object columns.

Upload a file with a signed URL

Request an upload URL, then send the file straight to storage:

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

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

The upload URL is valid for 30 minutes and carries its own signature, so send no authorization header with the PUT.

Keep the path from the response. Narrative assigns its own storage path, which does not match the name you requested, and the ingest request needs Narrative’s path rather than yours.

Then ingest the file into the dataset, passing that path as source_file:

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>"}'

Ingestion runs in the background. Watch the record count on the dataset to know when it has finished:

curl -s https://api.narrative.io/datasets/{dataset_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → .stats.active_dataset_stored_records

The count moves from zero to your row count, typically within a couple of minutes. Each ingested file adds a new snapshot to the dataset, and every active connection on the dataset delivers that snapshot.

Write files to a managed S3 bucket

A managed bucket is an S3 bucket that Narrative creates for your company. You write each batch of files into its own folder under the dataset’s path in the bucket, then write an empty _NIO_COMMIT file into that batch folder. Narrative ingests every file in the batch folder when the commit file appears, so you make no upload or ingest request. A file can be as large as S3 accepts. See Ingesting Files from a Managed S3 Bucket to create the bucket, grant your AWS account access, and lay out the folders.

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

All connectors

1. Create the dataset

Required columns

2. Confirm Meta accepts the dataset

3. Get a test event code

4. Create the connection

5. Upload events

Choose a file format

Upload a file with a signed URL

Write files to a managed S3 bucket

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

​Required columns

​2. Confirm Meta accepts the dataset

​3. Get a test event code

​4. Create the connection

​5. Upload events

​Choose a file format

​Upload a file with a signed URL

​Write files to a managed S3 bucket

​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

Required columns

2. Confirm Meta accepts the dataset

3. Get a test event code

4. Create the connection

5. Upload events

Choose a file format

Upload a file with a signed URL

Write files to a managed S3 bucket

6. Check the events at Meta

Going live

Keeping events flowing

Stopping delivery

Troubleshooting

Getting help

Related content