> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Connector API

> Deliver Custom Audiences and conversion events to Meta over the API, and set up what every Meta API guide needs

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](#prerequisites) and [set up API access](#set-up-api-access) on this page before you follow either guide.

## Choose a guide

<CardGroup cols={2}>
  <Card title="Custom Audience delivery" icon="users" href="/guides/connector-apis/meta/audiences-api">
    Upload hashed identifiers and deliver them into a new or existing Custom Audience in one ad account.
  </Card>

  <Card title="Conversion events" icon="cart-shopping" href="/guides/connector-apis/meta/conversion-events-api">
    Send offline conversion events to a Meta dataset through the Conversions API, starting with test events.
  </Card>
</CardGroup>

## Prerequisites

What you need depends on the guide you follow:

| Prerequisite | Audiences | Conversion events |
| - | :-: | :-: |
| [API key](#api-key) | ✓ | ✓ |
| [Facebook Connector installed](#facebook-connector-installed) | ✓ | ✓ |
| [A connected Meta profile](#a-connected-meta-profile) | ✓ | ✓ |
| [An ad account that accepts Custom Audiences](#an-eligible-ad-account) | ✓ | |
| [A Meta dataset ID](#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](/account-settings/api-keys) for the procedure and the [Permissions Reference](/reference/security/permissions) 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:

```bash theme={null}
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:

<Steps>
  <Step title="Open the connector">
    In Narrative, go to **Installed Apps** and select **Facebook Connector**.
  </Step>

  <Step title="Choose a profile type">
    Choose **System user** for an integration. With a system-user profile, you name the ad account on each connection.
  </Step>

  <Step title="Sign in to Meta">
    Sign in to Meta in the popup and grant Narrative access to your business.
  </Step>
</Steps>

Every request in these guides then uses the profile ID. [Find your profile](#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](#list-your-ad-accounts) shows both. See [Ad Account Eligibility for Custom Audiences](/guides/connectors/meta/ad-account-access) 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](#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](#facebook-connector-installed):

```bash theme={null}
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:

```bash theme={null}
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`.

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

### Find your profile

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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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](/reference/webhooks/event-reference#app-subscription) for the subscription fields and [Verifying deliveries](/reference/webhooks/event-reference#verifying-deliveries) for checking the secret.

***

## Related content

<CardGroup cols={2}>
  <Card title="Meta Custom Audiences Connector" icon="meta" href="/reference/connectors/meta">
    Supported identifiers and audience membership duration
  </Card>

  <Card title="Meta Conversions API Connector" icon="meta" href="/reference/connectors/meta-conversions-api">
    Every `meta_conversion_event` field, event name, and action source
  </Card>

  <Card title="Connector Interfaces" icon="plug" href="/concepts/data-activation/connector-interfaces">
    Why a dataset connects to an interface rather than a connector
  </Card>

  <Card title="API Keys" icon="key" href="/account-settings/api-keys">
    Create and rotate keys for programmatic access
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.