Reddit Connector API - Narrative I/O Knowledge Base

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 either guide.

Choose a guide

Custom Audience delivery

Upload hashed emails and deliver them into a new or existing Reddit Custom Audience.

Invite a partner

Send an invite link to someone who manages another Reddit Ads account, so you can deliver audiences to it.

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.

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.

What the connection does

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

New Custom Audience (`audience_new`)

The connector creates the Custom Audience in Reddit when you create the connection.

Field	What it does	Allowed values	Default
`ad_account_id`	The ad account the audience is created in	An ad account the profile can reach	None. Required
`audience_name`	The audience’s name in Reddit Ads	3 to 500 characters	None. Required
`dataset_write_mode`	How each delivery changes the audience: `append` adds members, `overwrite` replaces them	`append`, `overwrite`	`append`
`ttl_days`	With `append`, removes a member this many days after the last delivery that included it	1 to 28	None. Members stay until removed
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`true`

Existing Custom Audience (`audience_existing`)

Field	What it does	Allowed values	Default
`audience_id`	The Custom Audience to deliver to	The ID of a customer list audience the profile can reach, which starts with `ca.`	None. Required
`dataset_write_mode`	How each delivery changes the audience	`append`, `overwrite`	`append`
`historical_data_enabled`	Whether the connection also delivers data already in the dataset	`true`, `false`	`true`

The write mode and member TTL belong to the audience. The first connection to an audience that uses overwrite or ttl_days sets them, and every later connection to that audience must use the same values.

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 Reddit, historical_data_enabled delivers the dataset’s snapshots from the 30 days before the connection was created, as one delivery. After that, each new snapshot is delivered as it lands. What a delivery does depends on the write mode:

append without ttl_days adds the delivery’s members to the audience. Members stay until you remove them in Reddit.
append with ttl_days adds new members and restarts the clock for members the delivery includes again. A daily run removes each member whose last delivery is more than ttl_days days old, so a member can stay up to one day past the TTL.
overwrite makes the audience match the delivery. Members missing from the delivered snapshot are removed, and new ones are added.

An overwrite connection replaces the audience with each snapshot, so pair it with a dataset whose own write_mode is overwrite. Each snapshot of that dataset holds the full audience.

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.