Setting Up API Access for Snapchat

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 and set up API access on this page before you follow any Snapchat API guide. The guides are listed under Guides on the Snapchat Connector reference page.

Prerequisites

What you need depends on the guide you follow:

Prerequisite	Customer lists	Conversion events
API key	✓	✓
Snapchat Connector installed	✓	✓
A connected Snapchat profile	✓	✓
An ad account on the profile	✓
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 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.

Snapchat Connector installed

The Snapchat Connector is app 22. 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": 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:

Open the connector

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

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.

Connect to Snapchat

Choose Connect to Snapchat, sign in to Snapchat in the window that opens, and approve the access request.

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 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:

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://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.

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 Snapchat profile in your company. To read one:

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

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": "[email protected]",
#           "organization_id": "<ORGANIZATION_ID>", "display_name": "[email protected]",
#           "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:

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:

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:

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.

Connection settings

For the quick_settings each connection accepts and how a delivery treats existing and new rows, see API connection settings on the Snapchat Connector reference page.

Delivery notifications

The Snapchat Connector reports each delivery as an app webhook event. Subscribe a webhook to app 22 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": 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 for the subscription fields and Verifying deliveries for checking the secret.

Snapchat Connector

Supported identifiers and audience retention

Connector Interfaces

Why a dataset connects to an interface rather than a connector

Webhook Event Reference

Subscription fields, delivery payloads, and verification

API Keys

Create and rotate keys for programmatic access

Overview

All connectors

Prerequisites

API key

Snapchat Connector installed

A connected Snapchat profile

A Snap Pixel ID

Set up API access

Get an installation token

Find your profile

Check the profile’s Snapchat authorization

List your advertisers

Connection settings

Delivery notifications

Snapchat Connector

Connector Interfaces

Webhook Event Reference

API Keys

​Prerequisites

​API key

​Snapchat Connector installed

​A connected Snapchat profile

​A Snap Pixel ID

​Set up API access

​Get an installation token

​Find your profile

​Check the profile’s Snapchat authorization

​List your advertisers

​Connection settings

​Delivery notifications

​Related content

Snapchat Connector

Connector Interfaces

Webhook Event Reference

API Keys

Prerequisites

API key

Snapchat Connector installed

A connected Snapchat profile

A Snap Pixel ID

Set up API access

Get an installation token

Find your profile

Check the profile’s Snapchat authorization

List your advertisers

Connection settings

Delivery notifications

Related content