Meta Connector API - Narrative I/O Knowledge Base

The Meta Connector API lets an unattended integration deliver audiences to Meta Custom Audiences and send conversion events to Meta’s Conversions API. A person signs in once to create an API key and once to connect your Meta business, and the integration works from the API key after that. Complete the prerequisites and set up API access on this page before you follow either guide.

Choose a guide

Custom Audience delivery

Upload hashed identifiers and deliver them into a new or existing Custom Audience in one ad account.

Conversion events

Send offline conversion events to a Meta dataset through the Conversions API, starting with test events.

Prerequisites

What you need depends on the guide you follow:

Prerequisite	Audiences	Conversion events
API key	✓	✓
Facebook Connector installed	✓	✓
A connected Meta profile	✓	✓
An ad account that accepts Custom Audiences	✓
A Meta dataset ID		✓

API key

Create the key under Settings → API Keys with read and write on datasets and connections, write on uploads, and read on installations. Add write on webhooks if you want delivery notifications. See API Keys for the procedure and the Permissions Reference for what each resource covers. Create it from a shared team account rather than a personal login, so the integration keeps working when someone changes roles.

Facebook Connector installed

The Facebook Connector is app 8. Find your installation of it:

curl -s "https://api.narrative.io/installations?app_categories=destination_connector" \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# find the record with "app_id": 8 and note its "id"

Record the installation ID. If no record has "app_id": 8, install the Facebook Connector from the Narrative Marketplace.

A connected Meta profile

A connector profile holds the Meta credentials that every delivery uses. You create it once per Meta business, in the Narrative UI:

Open the connector

In Narrative, go to Installed Apps and select Facebook Connector.

Choose a profile type

Choose System user for an integration. With a system-user profile, you name the ad account on each connection.

Every request in these guides then uses the profile ID. Find your profile shows how to look it up.

An eligible ad account

Custom Audiences go into an ad account that belongs to a Business Manager and has accepted Meta’s Custom Audience terms. List your ad accounts shows both. See Ad Account Eligibility for Custom Audiences to fix an account that does not qualify.

A Meta dataset ID

Conversion events go to a Meta dataset, which Events Manager also calls a pixel. Its numeric ID is on the dataset’s page in Events Manager, and List your Meta datasets returns it.

Set up API access

The guides talk to two hosts, and each takes its own credential:

Host	Base URL	Credential	Handles
Narrative API	`https://api.narrative.io`	Your API key	Datasets, uploads, connections, webhooks
Meta connector	`https://facebook.narrativeconnectors.com`	An installation token	Profiles, ad accounts, Meta datasets

Get an installation token

The Meta connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from Facebook Connector installed:

curl -s -X POST https://api.narrative.io/installations/{installation_id}/token \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"access_token": "<INSTALLATION_TOKEN>", "access_token_expires_in": 10799,
#    "refresh_token": "<REFRESH_TOKEN>", "refresh_token_expires_in": 86399}

Store access_token as $INSTALLATION_TOKEN. It lasts about three hours, so request a new one at the start of each run of your integration. Confirm that both hosts answer:

curl -s https://api.narrative.io/company-info/whoami \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"id": 1234}

curl -s https://facebook.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"type": "system_user", "id": "<PROFILE_ID>", "status": "enabled", ...}]}

Send the API key to api.narrative.io and the installation token to facebook.narrativeconnectors.com.

API keys contain characters that shells mangle. Read the key from a file or an environment variable rather than pasting it inline.

Find your profile

GET /profiles lists every Meta profile in your company. To read one:

curl -s https://facebook.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"type": "system_user", "id": "<PROFILE_ID>", "name": "Example Brand",
#    "status": "enabled",
#    "token": {"is_valid": true,
#              "scopes": ["ads_management", "business_management", "public_profile"], ...}, ...}

Use a profile whose status is enabled and whose token.is_valid is true. Record its id.

List your ad accounts

curl -s https://facebook.narrativeconnectors.com/profiles/{profile_id}/ad-accounts \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "act_<AD_ACCOUNT_ID>", "name": "Example Brand",
#    "business": {"id": "<BUSINESS_ID>", "name": "Example Brand Inc."},
#    "supports_custom_audiences": true, "user_accepted_custom_audience_tos": true}]}

Choose an account where both supports_custom_audiences and user_accepted_custom_audience_tos are true. You can use the ID with or without the act_ prefix.

List your Meta datasets

curl -s https://facebook.narrativeconnectors.com/profiles/{profile_id}/ads-datasets \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": <META_DATASET_ID>, "name": "Offline Sales"}]}

id is a number. Conversion events carry it in meta_dataset_id.

What the connection does

A connection’s quick_settings pick the interface and set how the connection delivers. The fields depend on the interface.

New Custom Audience (`audience_first_party_new`)

The connector creates the Custom Audience in Meta when you create the connection.

Field	What it does	Allowed values	Default
`ad_account_id`	The ad account the audience is created in	An ad account ID, with or without the `act_` prefix	None. Required for a system-user profile
`audience_name`	The audience’s name in Ads Manager	Up to 64 characters	`Connection <connection ID> Audience`
`audience_description`	The audience’s description. The connector sends the first 100 characters to Meta	Any string	Empty
`membership_duration_days`	How many days a member stays in the audience. Set once, when the audience is created	1 or more	Meta’s default retention
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`false`

Existing Custom Audience (`audience_first_party_existing`)

Field	What it does	Allowed values	Default
`audience_id`	The Custom Audience to add members to. The audience keeps its own retention	The ID from the Audience ID column in Ads Manager, for an audience the profile can reach	None. Required
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`false`

Conversion events (`conversion_events`)

Field	What it does	Allowed values	Default
`test_event_code`	Sends every event as a test event, which appears in the Test events tab and does not count as a conversion	The code from Test events in Events Manager	None. Events count as conversions
`historical_data_enabled`	Whether the connection also sends events already in the dataset	`true`, `false`	`false`

Each event names its Meta dataset in meta_dataset_id, so the connection has no Meta dataset setting.

Existing and new rows

A connection delivers every snapshot written to the dataset after the connection is created. The historical_data_enabled quick setting decides whether the connection also delivers data that was already in the dataset when you created it:

With historical_data_enabled set to true, the connection first delivers data already in the dataset, then keeps delivering new snapshots as they land.
With historical_data_enabled set to false, the connection delivers only snapshots written after it was created.

How far back the first delivery reaches depends on the connector, and each connector’s guide states it. For Meta, historical_data_enabled delivers everything in the dataset when the connection is created. After that, each new snapshot is delivered as it lands. An audience connection adds members and never removes them. A member leaves the Custom Audience when its retention runs out. When you overwrite the dataset, the connection adds the rows in the new snapshot, and members missing from it stay in the audience until their retention ends. A conversion connection sends each event in each snapshot it delivers. Uploading the same events again in a new snapshot sends them again, and so does a second connection with historical_data_enabled set to true.

Delivery notifications

The Facebook Connector reports each delivery as an app webhook event. Subscribe a webhook to app 8 to receive them:

curl -s -X POST https://api.narrative.io/webhooks \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook_subscription_app",
    "app_id": 8,
    "url": "https://your-host.example/hooks/narrative",
    "name": "meta-deliveries"
  }'
# → {"id": "<WEBHOOK_ID>", "app_id": 8, "secret": "<WEBHOOK_SECRET>", "status": "active", ...}

Keep the secret to verify each delivery. The connector sends these events:

Event	Sent when
`audience.delivery.completed`	A delivery to a Custom Audience finishes
`audience.delivery.failed`	A delivery to a Custom Audience fails
`conversion.delivery.completed`	A delivery of conversion events finishes
`conversion.delivery.failed`	A delivery of conversion events fails

To stop the notifications, delete the subscription with DELETE /webhooks/{webhook_id}. See App subscription for the subscription fields and Verifying deliveries for checking the secret.

Meta Custom Audiences Connector

Supported identifiers and audience membership duration

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

​Choose a guide

Custom Audience delivery

Conversion events

​Prerequisites

​API key

​Facebook Connector installed

​A connected Meta profile

​An eligible ad account

​A Meta dataset ID

​Set up API access

​Get an installation token

​Find your profile

​List your ad accounts

​List your Meta datasets

​What the connection does

​New Custom Audience (audience_first_party_new)

​Existing Custom Audience (audience_first_party_existing)

​Conversion events (conversion_events)

​Existing and new rows

​Delivery notifications

​Related content

Meta Custom Audiences Connector

Meta Conversions API Connector

Connector Interfaces

API Keys

Choose a guide

Prerequisites

API key

Facebook Connector installed

A connected Meta profile

An eligible ad account

A Meta dataset ID

Set up API access

Get an installation token

Find your profile

List your ad accounts

List your Meta datasets

What the connection does

New Custom Audience (`audience_first_party_new`)

Existing Custom Audience (`audience_first_party_existing`)

Conversion events (`conversion_events`)

Existing and new rows

Delivery notifications

Related content