> ## 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.

# Snapchat Connector API

> Deliver customer lists and conversion events to Snapchat over the API, and set up what every Snapchat API guide needs

The Snapchat Connector API lets an unattended integration deliver customer lists to Snapchat and send conversion events to a Snap Pixel through Snapchat's Conversions API. A person signs in once to create an API key and once to connect your Snapchat organization, 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="Customer list delivery" icon="users" href="/guides/connector-apis/snapchat/audiences-api">
    Upload hashed identifiers and deliver them into a new customer list in one ad account.
  </Card>

  <Card title="Conversion events" icon="cart-shopping" href="/guides/connector-apis/snapchat/conversion-events-api">
    Send offline conversion events to a Snap Pixel through the Conversions API, starting in test mode.
  </Card>
</CardGroup>

## Prerequisites

What you need depends on the guide you follow:

| Prerequisite | Customer lists | Conversion events |
| - | :-: | :-: |
| [API key](#api-key) | ✓ | ✓ |
| [Snapchat Connector installed](#snapchat-connector-installed) | ✓ | ✓ |
| [A connected Snapchat profile](#a-connected-snapchat-profile) | ✓ | ✓ |
| [An ad account on the profile](#list-your-advertisers) | ✓ | |
| [A Snap Pixel ID](#a-snap-pixel-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 read and write on `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.

### Snapchat Connector installed

The Snapchat Connector is app `22`. 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": 22 and note its "id"
```

Record the installation ID. If no record has `"app_id": 22`, install the Snapchat Connector from the Narrative Marketplace.

### A connected Snapchat profile

A connector profile holds the Snapchat authorization that every delivery uses. You create it once per Snapchat organization, in the Narrative UI:

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

  <Step title="Create a profile">
    In the **Profiles** tab, choose **New Profile**. Enter a name and your Snapchat **Organization ID**, which is under **Business Details** in Snapchat Business Manager.
  </Step>

  <Step title="Connect to Snapchat">
    Choose **Connect to Snapchat**, sign in to Snapchat in the window that opens, and approve the access request.
  </Step>
</Steps>

Narrative then loads the ad accounts in that organization into the profile as advertisers. Every request in these guides uses the profile ID, and [Find your profile](#find-your-profile) shows how to look it up.

### A Snap Pixel ID

Conversion events go to a Snap Pixel that your Snapchat organization owns. Copy the Pixel ID from **Events Manager** in Snapchat Ads Manager.

## 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 |
| Snapchat connector | `https://snapchat.narrativeconnectors.com` | An installation token | Profiles, advertisers, Snapchat authorization |

### Get an installation token

The Snapchat connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from [Snapchat Connector installed](#snapchat-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://snapchat.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<PROFILE_ID>", "name": "Example Brand", "status": "enabled",
#    "organization_id": "<ORGANIZATION_ID>", ...}]}
```

Send the API key to `api.narrative.io` and the installation token to `snapchat.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 Snapchat profile in your company. To read one:

```bash theme={null}
curl -s https://snapchat.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "created_at": "2026-08-05T18:52:04.299146Z",
#    "name": "Example Brand", "status": "enabled",
#    "updated_at": "2026-08-05T18:52:04.299146Z", "organization_id": "<ORGANIZATION_ID>"}
```

Use a profile whose `status` is `enabled`. Record its `id`.

### Check the profile's Snapchat authorization

```bash theme={null}
curl -s https://snapchat.narrativeconnectors.com/profiles/{profile_id}/snapchat-user \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"request_status": "SUCCESS", "request_id": "<REQUEST_ID>",
#    "me": {"id": "<SNAPCHAT_USER_ID>", "email": "ads@example.com",
#           "organization_id": "<ORGANIZATION_ID>", "display_name": "ads@example.com",
#           "member_status": "MEMBER", ...}}
```

A `request_status` of `SUCCESS` means the profile is connected and ready to deliver. The `me` object shows the Snapchat user who approved access.

### List your advertisers

Advertisers are the Snapchat ad accounts the profile can deliver to:

```bash theme={null}
curl -s https://snapchat.narrativeconnectors.com/profiles/{profile_id}/advertisers \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}]}
```

To read one advertiser:

```bash theme={null}
curl -s https://snapchat.narrativeconnectors.com/profiles/{profile_id}/advertisers/{ad_account_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}
```

When you add an ad account in Snapchat after connecting the profile, reload the profile's advertisers:

```bash theme={null}
curl -s -X POST https://snapchat.narrativeconnectors.com/profiles/{profile_id}/advertisers/refresh \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}]}
```

The response lists every advertiser on the profile after the reload.

## What the connection does

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

### Customer list (`audience`)

The connector creates a new customer list in Snapchat when you create the connection.

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `ad_account_id` | The ad account the customer list is created in | The UUID of an ad account the profile can reach | None. Required |
| `name` | The customer list's name in Ads Manager | Up to 375 characters | None. Required |
| `description` | The customer list's description | Any string | None |
| `retention_in_days` | How many days Snapchat keeps an uploaded user in the list. Set once, when the list is created | A whole number of days | Snapchat's default retention |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `true` |

### Conversion events (`conversion_events`)

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `test_mode_enabled` | Sends events to Snapchat's validation endpoint, which checks each event without recording it | `true`, `false` | `false` |
| `historical_data_enabled` | Whether the connection also sends events already in the dataset | `true`, `false` | `true` |

Each event names its pixel in `snapchat_conversion_event.snapchat_pixel_id`, so the connection has no pixel setting. The connection sends events whose `event_time` falls within the last 62 days and no more than 10 minutes in the future.

### 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 Snapchat, `historical_data_enabled` delivers the dataset's snapshots from the 30 days before the connection was created. After that, each new snapshot is delivered as it lands.

A customer list connection adds users and never removes them. A user leaves the list when its retention runs out. When you overwrite the dataset, the connection adds the rows in the new snapshot, and users missing from it stay in the list 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.

## Delivery notifications

The Snapchat Connector reports each delivery as an app webhook event. Subscribe a webhook to app `22` 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": 22,
    "url": "https://your-host.example/hooks/narrative",
    "name": "snapchat-deliveries"
  }'
# → {"id": "<WEBHOOK_ID>", "app_id": 22, "name": "snapchat-deliveries",
#    "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 customer list finishes |
| `audience.delivery.failed` | A delivery to a customer list fails |
| `conversion.delivery.completed` | A delivery of conversion events finishes |
| `conversion.delivery.failed` | A delivery of conversion events fails |

Read a subscription with `GET /webhooks/{webhook_id}`. 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="Snapchat Connector" icon="snapchat" href="/reference/connectors/snapchat">
    Supported identifiers and audience retention
  </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="Webhook Event Reference" icon="webhook" href="/reference/webhooks/event-reference">
    Subscription fields, delivery payloads, and verification
  </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.