Meta Connector API

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, uploads, connections, and installations, and read on jobs. Add 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. Keep the act_ prefix when you use the ID.

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.

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

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

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

Delivery notifications

Meta Custom Audiences Connector

Meta Conversions API Connector

Connector Interfaces

API Keys

​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

​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

Delivery notifications

Related content