Setting Up API Access for Meta

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 any Meta API guide. The guides are listed under Guides on the Meta Custom Audiences Connector and Meta Conversions API Connector reference pages.

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.

Connection settings

For the quick_settings each connection accepts and how a delivery treats existing and new rows, see API connection settings on the Meta Custom Audiences Connector and Meta Conversions API Connector reference pages.

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

All connectors

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

Connection settings

Delivery notifications

Meta Custom Audiences Connector

Meta Conversions API Connector

Connector Interfaces

API Keys

​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

​Connection settings

​Delivery notifications

​Related content

Meta Custom Audiences Connector

Meta Conversions API Connector

Connector Interfaces

API Keys

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

Connection settings

Delivery notifications

Related content