Setting Up API Access for Reddit

The Reddit Connector API lets an unattended integration deliver hashed identifiers into Custom Audiences in your Reddit Ads account. You sign in to Narrative once to create an API key, and you connect your Reddit Ads account once. The integration works from the API key after that. To deliver to a Reddit Ads account that someone else owns, such as a client’s, send that person a partner invite. They connect their account, and you deliver to it the same way. Complete the prerequisites and set up API access on this page before you follow any Reddit API guide. The guides are listed under Guides on the Reddit Connector reference page.

Prerequisites

What you need depends on the guide you follow:

Prerequisite	Custom Audiences	Partner invites
API key	✓	✓
Reddit Connector installed	✓	✓
A connected Reddit profile	✓
A Reddit ad account on the profile	✓

API key

Create the key under Settings → API Keys with these permissions:

Read and write on datasets and connections
Write on uploads
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.

Reddit Connector installed

The Reddit Connector is app 23. 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": 23 and note its "id"

Record the installation ID. If no record has "app_id": 23, install the Reddit Connector from the Narrative Marketplace.

A connected Reddit profile

A connector profile holds the Reddit authorization that every delivery uses. One profile reaches every ad account that the approving Reddit user can manage. To deliver to your own Reddit Ads account, create a profile and approve Narrative on Reddit once, as described in Connect your Reddit Ads account. To deliver to an account someone else owns, invite a partner instead. The partner’s approval creates the profile.

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
Reddit connector	`https://reddit.narrativeconnectors.com`	An installation token	Profiles, ad accounts, invites, Reddit authorization

Get an installation token

The Reddit connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from Reddit 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://reddit.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<PROFILE_ID>", "created_at": "2026-09-22T10:40:00Z",
#    "name": "Example Brand", "status": "enabled",
#    "updated_at": "2026-09-22T10:47:00Z"}]}

Send the API key to api.narrative.io and the installation token to reddit.narrativeconnectors.com.

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

Connect your Reddit Ads account

Connect your Reddit Ads account once. Every delivery after that runs from your API key.

Create a profile

In Narrative, go to Installed Apps → Reddit Connector. In the Profiles tab, click Add profile, enter a profile name, and click Create profile.

Approve Narrative on Reddit

Click Connect to Reddit, sign in to the Reddit account that manages your ad accounts, and click Allow. The profile shows Connected once Reddit confirms.

Setting Up the Reddit Connector covers these steps in more detail. To approve Narrative from your integration instead of clicking Connect to Reddit, request an authorization link for the profile. Find your profile shows how to get its ID:

curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id}/authorize \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"url": "https://www.reddit.com/api/v1/authorize?client_id=<CLIENT_ID>&redirect_uri=https://reddit.narrativeconnectors.com/reddit/callback&response_type=code&duration=permanent&scope=adsread+adsedit&state=<STATE>",
#    "expires_at": "2026-10-04T15:31:00Z"}

Open the url in a browser before expires_at, sign in to Reddit, and approve Narrative. The profile then uses your Reddit authorization.

Find your profile

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

curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "created_at": "2026-09-22T10:40:00Z",
#    "name": "Example Brand", "status": "enabled",
#    "updated_at": "2026-09-22T10:47:00Z"}

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

List your ad accounts

Audiences are created under a Reddit ad account. List the ad accounts the profile can deliver to:

curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}]}

Reddit ad account IDs start with a2_. To read one ad account:

curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts/{ad_account_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}

When the Reddit user gains access to another ad account after connecting the profile, reload the profile’s ad accounts from Reddit:

curl -s -X POST https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts/refresh \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}]}

The response lists every ad account 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 Reddit Connector reference page.

Delivery notifications

The Reddit Connector reports each delivery as an app webhook event. Subscribe a webhook to app 23 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": 23,
    "url": "https://your-host.example/hooks/narrative",
    "name": "reddit-deliveries"
  }'
# → {"id": "<WEBHOOK_ID>", "app_id": 23, "name": "reddit-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 Custom Audience finishes
`audience.delivery.failed`	A delivery to a Custom Audience fails
`audience.expiry.completed`	Members leave an audience because their `ttl_days` period ran out
`audience.expiry.failed`	Removing members whose `ttl_days` period ran out 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.

Reddit Connector

Supported identifiers, profiles, and invites

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

Reddit Connector installed

A connected Reddit profile

Set up API access

Get an installation token

Connect your Reddit Ads account

Find your profile

List your ad accounts

Connection settings

Delivery notifications

Reddit Connector

Connector Interfaces

Webhook Event Reference

API Keys

​Prerequisites

​API key

​Reddit Connector installed

​A connected Reddit profile

​Set up API access

​Get an installation token

​Connect your Reddit Ads account

​Find your profile

​List your ad accounts

​Connection settings

​Delivery notifications

​Related content

Reddit Connector

Connector Interfaces

Webhook Event Reference

API Keys

Prerequisites

API key

Reddit Connector installed

A connected Reddit profile

Set up API access

Get an installation token

Connect your Reddit Ads account

Find your profile

List your ad accounts

Connection settings

Delivery notifications

Related content