Delivering Custom Audiences to Reddit via the API

This guide shows you how to build an unattended integration that uploads an audience to Narrative and delivers it into a Reddit Custom Audience. Reddit calls these audiences customer lists. You can have Narrative create a new audience in one of your ad accounts, or deliver into an audience you already have. Before you start, complete the prerequisites and set up API access. You need a profile ID and an ad account ID from List your ad accounts. Every request in this guide goes to https://api.narrative.io with your API key.

1. Create the dataset

The dataset must carry at least one identifier column that Reddit can match on. Required columns lists them.

curl -X POST https://api.narrative.io/datasets \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "spring_buyers_reddit",
    "display_name": "Spring Buyers (Reddit)",
    "description": "Hashed emails for Reddit",
    "write_mode": "append",
    "schema": {
      "file_config": { "type": "json", "normalize_field_names": false },
      "type": "object",
      "properties": {
        "sha256_hashed_email": {
          "type": "object",
          "properties": { "value": { "type": "string" } }
        }
      }
    }
  }'
# → {"id": 12345, "status": "pending", ...}

Record the id in the response.

Required columns

Both interfaces take the same schema. The dataset needs at least one of these identifier columns:

Column	Shape of each value
`hashed_email`	`{"value": ..., "type": "..."}`
`raw_email`	A string
`sha256_hashed_email`	`{"value": ...}`
`mobile_id_unique_identifier`	`{"value": ..., "type": "..."}`
`apple_idfa`	`{"value": ...}`
`android_advertising_id`	`{"value": ...}`
`narrative_id`	`{"context": "...", "value": ...}`
`unique_id`	`{"value": ..., "type": "..."}`

Each identifier column is named after its Rosetta Stone attribute, and the connector matches on that column name. A column holds either a plain string or an object. In the dataset schema, declare a string column with "type": "string", and declare an object column with "type": "object" and its properties:

{
  "type": "object",
  "properties": {
    "<string_attribute>": { "type": "string" },
    "<object_attribute>": {
      "type": "object",
      "properties": { "<property>": { "type": "<type>" } }
    }
  }
}

Send an object column as an object in each row:

{"<string_attribute>": "...", "<object_attribute>": {"<property>": "..."}}

See your connector’s reference page for the attributes it accepts and their exact shapes. A row with one identifier looks like this:

{"sha256_hashed_email": {"value": "<SHA-256 of the trimmed, lowercased email>"}}

See Supported identifiers for how the destination matches each identifier.

2. Activate the dataset

curl -X POST https://api.narrative.io/datasets/{dataset_id}/activate \
  -H "Authorization: Bearer $NIO_API_TOKEN"

The response is 201 with the dataset, now "status": "active". Activation locks the schema, so activate only once the shape is settled.

3. Upload and ingest your file

Each line of the file is one row that matches the schema you declared in step 1. For the columns Reddit accepts and their shapes, see Supported identifiers and Required columns. You can load a file into a dataset over the API in two ways:

Signed-URL upload. Your integration uploads one file of up to 3 GB, then asks Narrative to ingest it.
Managed S3 bucket. You write files to an S3 bucket that Narrative manages, and Narrative ingests each batch on its own. Use a managed bucket for files larger than 3 GB, or for files that another system delivers on a schedule.

Choose a file format

The dataset’s file_config.type sets the format of every file you load into it. Parquet and JSON Lines both hold object columns, which nest properties inside one column:

Parquet (parquet) is the most compatible format for connector datasets. It stores nested struct columns and their types natively, and Narrative matches columns to the schema by name at every level.
JSON Lines (json) holds one JSON object per line. Narrative matches each nested object to the schema by name.

CSV datasets (flat) hold only scalar columns, so they can’t carry object columns.

Upload a file with a signed URL

Request an upload URL, then send the file straight to storage:

curl -X POST https://api.narrative.io/uploads/my-file.jsonl \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"path": "<UPLOAD_PATH>", "url": "https://...", "expiry": "..."}

curl -X PUT "<url from the response>" --upload-file ./my-file.jsonl

The upload URL is valid for 30 minutes and carries its own signature, so send no authorization header with the PUT.

Keep the path from the response. Narrative assigns its own storage path, which does not match the name you requested, and the ingest request needs Narrative’s path rather than yours.

Then ingest the file into the dataset, passing that path as source_file:

curl -X POST https://api.narrative.io/datasets/{dataset_id}/upload \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_file": "<UPLOAD_PATH>"}'

Ingestion runs in the background. Watch the record count on the dataset to know when it has finished:

curl -s https://api.narrative.io/datasets/{dataset_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → .stats.active_dataset_stored_records

The count moves from zero to your row count, typically within a couple of minutes. Each ingested file adds a new snapshot to the dataset, and every active connection on the dataset delivers that snapshot.

Write files to a managed S3 bucket

A managed bucket is an S3 bucket that Narrative creates for your company. You write each batch of files into its own folder under the dataset’s path in the bucket, then write an empty _NIO_COMMIT file into that batch folder. Narrative ingests every file in the batch folder when the commit file appears, so you make no upload or ingest request. A file can be as large as S3 accepts. See Ingesting Files from a Managed S3 Bucket to create the bucket, grant your AWS account access, and lay out the folders.

4. Confirm Reddit accepts the dataset

Before you create a connection, ask Narrative which connector interfaces the dataset satisfies:

curl -s https://api.narrative.io/datasets/{dataset_id}/interfaces \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"dataset_id": 12345,
#    "accepted": [{"app_id": <APP_ID>, "interface_id": "<INTERFACE_ID>"}, ...],
#    "errors": [{"app_id": <APP_ID>, "interface_id": "<INTERFACE_ID>", "details": {...}}, ...]}

The response checks the dataset’s schema against every interface of the connectors your company has installed, and sorts the results into two lists:

accepted lists each interface you can connect the dataset to, by the connector’s app_id and the interface_id.
errors lists each interface the schema does not satisfy. Its details hold the reason, such as "required property '<column>' not found".

Add ?tags=<tag> to check only the interfaces that carry that tag. When the interface you want is under errors, the dataset’s schema doesn’t meet what the interface needs, for example a missing column or property. Activation locks the schema, so create a new dataset that fixes what the error names. For Reddit, look for the Reddit Connector ("app_id": 23) in accepted. Add ?tags=reddit to check only the Reddit interfaces. audience_new delivers to a new audience and audience_existing delivers to one you already have:

{"app_id": 23, "interface_id": "audience_existing"},
{"app_id": 23, "interface_id": "audience_new"}

5. Create the connection

To deliver to a new Custom Audience, create a connection with the audience_new interface. The connector creates the Custom Audience in Reddit before it answers, so the audience exists in Reddit Ads Manager once you get 201.

curl -X POST https://api.narrative.io/v2/connections \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "connections_dataset",
    "dataset_id": 12345,
    "profile_id": "<PROFILE_ID>",
    "quick_settings": {
      "type": "audience_new",
      "ad_account_id": "<AD_ACCOUNT_ID>",
      "audience_name": "Spring Buyers",
      "historical_data_enabled": true,
      "dataset_write_mode": "append"
    }
  }'
# → 201 {"type": "connections_dataset", "id": "<CONNECTION_ID>",
#        "app": {"id": 23, "name": "Reddit Connector"}, "dataset_id": 12345,
#        "quick_settings": {"type": "audience_new", "ad_account_id": "<AD_ACCOUNT_ID>",
#                           "audience_name": "Spring Buyers", "dataset_write_mode": "append",
#                           "historical_data_enabled": true},
#        "profile_id": "<PROFILE_ID>", "profile": {"id": "<PROFILE_ID>", "name": "Example Brand"},
#        "status": "active", ...}

Both type fields are required. The outer one identifies what you are connecting, and the one inside quick_settings selects the delivery interface. What the connection does describes every field, its allowed values, and its default. Record the connection id. You need it to stop the delivery.

Replace the audience on each delivery

Set dataset_write_mode to overwrite when each delivery should replace the members from the previous delivery. Use a dataset created with "write_mode": "overwrite", so each snapshot holds the whole audience. In the request below, 12346 is an example ID for an existing dataset of that kind. Steps 1 to 3 create and load one; set write_mode to overwrite in step 1:

curl -X POST https://api.narrative.io/v2/connections \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "connections_dataset",
    "dataset_id": 12346,
    "profile_id": "<PROFILE_ID>",
    "quick_settings": {
      "type": "audience_new",
      "ad_account_id": "<AD_ACCOUNT_ID>",
      "audience_name": "Weekly Active Buyers",
      "historical_data_enabled": true,
      "dataset_write_mode": "overwrite"
    }
  }'
# → 201 {"type": "connections_dataset", "id": "<CONNECTION_ID>",
#        "quick_settings": {"type": "audience_new", "dataset_write_mode": "overwrite", ...},
#        "status": "active", ...}

Remove members after a number of days

Add ttl_days to an append connection so people leave the audience once your data stops including them:

curl -X POST https://api.narrative.io/v2/connections \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "connections_dataset",
    "dataset_id": 12345,
    "profile_id": "<PROFILE_ID>",
    "quick_settings": {
      "type": "audience_new",
      "ad_account_id": "<AD_ACCOUNT_ID>",
      "audience_name": "Cart Abandoners, Last 7 Days",
      "historical_data_enabled": true,
      "dataset_write_mode": "append",
      "ttl_days": 7
    }
  }'
# → 201 {"type": "connections_dataset", "id": "<CONNECTION_ID>",
#        "quick_settings": {"type": "audience_new", "ttl_days": 7,
#                           "dataset_write_mode": "append", ...},
#        "status": "active", ...}

Deliver to an existing audience

To add a dataset to an audience you already have in Reddit, copy the audience ID from Reddit Ads Manager. Reddit audience IDs start with ca.. Then create the connection with the audience_existing interface:

curl -X POST https://api.narrative.io/v2/connections \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "connections_dataset",
    "dataset_id": 12345,
    "profile_id": "<PROFILE_ID>",
    "quick_settings": {
      "type": "audience_existing",
      "audience_id": "<AUDIENCE_ID>",
      "historical_data_enabled": true
    }
  }'
# → 201 {"type": "connections_dataset", "id": "<CONNECTION_ID>",
#        "app": {"id": 23, "name": "Reddit Connector"}, "dataset_id": 12345,
#        "quick_settings": {"type": "audience_existing", "audience_id": "<AUDIENCE_ID>",
#                           "historical_data_enabled": true},
#        "profile_id": "<PROFILE_ID>", "status": "active", ...}

What the connection does describes every field, its allowed values, and its default.

6. Confirm the connection

curl -s https://api.narrative.io/v2/connections/{connection_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"

curl -s "https://api.narrative.io/v2/connections?app_id=23" \
  -H "Authorization: Bearer $NIO_API_TOKEN"

Both responses show the connection with "status": "active" and the quick_settings you sent. The second lists every Reddit connection in your company. For an audience_new connection, the audience appears in Reddit Ads Manager under the audience_name you set. To hear when each delivery finishes, subscribe to delivery notifications. The connector sends audience.delivery.completed when a delivery to the audience finishes.

Keeping the audience current

Write new data to the dataset with the same three calls as in step 3. The connection keeps running, so new rows reach the audience without further calls.

Stopping delivery

curl -X DELETE https://api.narrative.io/v2/connections/{connection_id} \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → 200 {}

Deleting the connection archives it and stops further deliveries. The audience stays in Reddit with its members. Delete it in Reddit Ads Manager if you no longer want it. To remove the dataset as well, send DELETE /datasets/{dataset_id}.

Troubleshooting

Symptom	Cause	Fix
`400` with `ad account does not exist: <AD_ACCOUNT_ID>`	The ad account is not on the profile	Use an `id` from List your ad accounts. If the account is new in Reddit, reload the ad accounts first
`400` with `Reddit custom audience <AUDIENCE_ID> was not found or is not reachable with this profile's grant`	The audience ID is wrong, or the audience is in an ad account the profile can’t reach	Copy the ID again from Reddit Ads Manager, and check that the profile lists the audience’s ad account

Getting help

Contact your Narrative relationship manager with your company ID, the dataset ID, and the failing request and response.

Inviting a partner via the API

Let a partner connect their Reddit Ads account so you can deliver to it

Reddit Connector

Supported identifiers, profiles, and invites

Connector Interfaces

Why a dataset connects to an interface rather than a connector

API Keys

Create and rotate keys for programmatic access

​1. Create the dataset

​Required columns

​2. Activate the dataset

​3. Upload and ingest your file

​Choose a file format

​Upload a file with a signed URL

​Write files to a managed S3 bucket

​4. Confirm Reddit accepts the dataset

​5. Create the connection

​Replace the audience on each delivery

​Remove members after a number of days

​Deliver to an existing audience

​6. Confirm the connection

​Keeping the audience current

​Stopping delivery

​Troubleshooting

​Getting help

​Related content

Inviting a partner via the API

Reddit Connector

Connector Interfaces

API Keys

1. Create the dataset

Required columns

2. Activate the dataset

3. Upload and ingest your file

Choose a file format

Upload a file with a signed URL

Write files to a managed S3 bucket

4. Confirm Reddit accepts the dataset

5. Create the connection

Replace the audience on each delivery

Remove members after a number of days

Deliver to an existing audience

6. Confirm the connection

Keeping the audience current

Stopping delivery

Troubleshooting

Getting help

Related content