> ## 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. # Reddit Connector API > Deliver Custom Audiences to your Reddit Ads account over the API, invite partners to connect their accounts, and set up what every Reddit API guide needs 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](/guides/connector-apis/reddit/connect-account-api). They connect their account, and you deliver to it the same way. Complete the [prerequisites](#prerequisites) and [set up API access](#set-up-api-access) on this page before you follow either guide. ## Choose a guide Upload hashed emails and deliver them into a new or existing Reddit Custom Audience. 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](#api-key) | ✓ | ✓ | | [Reddit Connector installed](#reddit-connector-installed) | ✓ | ✓ | | [A connected Reddit profile](#a-connected-reddit-profile) | ✓ | | | [A Reddit ad account on the profile](#list-your-ad-accounts) | ✓ | | ### 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](/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. ### Reddit Connector installed The Reddit Connector is app `23`. 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": 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](#connect-your-reddit-ads-account). To deliver to an account someone else owns, [invite a partner](/guides/connector-apis/reddit/connect-account-api) 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](#reddit-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": "", "access_token_expires_in": 10799, # "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://reddit.narrativeconnectors.com/profiles \ -H "Authorization: Bearer $INSTALLATION_TOKEN" # → {"records": [{"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. In Narrative, go to **Installed Apps → Reddit Connector**. In the **Profiles** tab, click **Add profile**, enter a profile name, and click **Create profile**. 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](/reference/connectors/reddit#installation) 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](#find-your-profile) shows how to get its ID: ```bash theme={null} 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=&redirect_uri=https://reddit.narrativeconnectors.com/reddit/callback&response_type=code&duration=permanent&scope=adsread+adsedit&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: ```bash theme={null} curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id} \ -H "Authorization: Bearer $INSTALLATION_TOKEN" # → {"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: ```bash theme={null} curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts \ -H "Authorization: Bearer $INSTALLATION_TOKEN" # → {"records": [{"id": "", "name": "Example Ad Account"}]} ``` Reddit ad account IDs start with `a2_`. To read one ad account: ```bash theme={null} curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts/{ad_account_id} \ -H "Authorization: Bearer $INSTALLATION_TOKEN" # → {"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: ```bash theme={null} curl -s -X POST https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts/refresh \ -H "Authorization: Bearer $INSTALLATION_TOKEN" # → {"records": [{"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: ```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": 23, "url": "https://your-host.example/hooks/narrative", "name": "reddit-deliveries" }' # → {"id": "", "app_id": 23, "name": "reddit-deliveries", # "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`](/guides/connector-apis/reddit/audiences-api#remove-members-after-a-number-of-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](/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 Supported identifiers, profiles, and invites Why a dataset connects to an interface rather than a connector Subscription fields, delivery payloads, and verification Create and rotate keys for programmatic access This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.