Run an Ad Campaign

Prerequisites

Before continuing, you should have already read:

In this Guide

Understanding the Ad Hierarchy

Before making any API calls, it helps to understand how advertising is structured on Spreaker. All three entities must exist before an ad can run — you will create them in order.

  • Advertiser — the brand or entity paying for the advertising. Holds IAB category information used for brand safety and classification.
    • Campaign — groups one or more line items under a single advertiser. Think of it as a flight or a product launch: a logical container that ties line items to a specific advertiser.
      • Line Item — where all the delivery rules live: the audio creative, the targeting, the pricing, the schedule, and the impression goal. This is what actually delivers the ad.

Step 1: Create an Advertiser

An advertiser must be created before you can set up any campaigns. The most important field besides the name is iab_categories, which classifies the advertiser’s content using the IAB Content Taxonomy. This is used for brand safety matching.

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" \
  -F "name=Acme Corp" \
  -F "iab_categories=IAB22-11" \
  https://api.spreaker.com/v2/advertisers

Save the advertiser_id from the response — you will need it in the next step.

{
  "response": {
    "advertiser": {
      "advertiser_id": 4978,
      "name": "Acme Corp",
      "iab_categories": "IAB22-11",
      "synched": false
    }
  }
}

The synched field will be false immediately after creation. This means the advertiser has not yet been propagated to the ad server. Syncing happens automatically in the background and is required before any ad can be delivered.

Step 2: Create a Campaign

A campaign ties together a group of line items under a single advertiser. Use the advertiser_id you received in Step 1.

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" \
  -F "name=Acme Summer Launch" \
  -F "advertiser_id=4978" \
  https://api.spreaker.com/v2/campaigns

Save the campaign_id from the response.

{
  "response": {
    "campaign": {
      "campaign_id": 9036,
      "name": "Acme Summer Launch",
      "advertiser_id": 4978,
      "advertiser_name": "Acme Corp",
      "status": "STOPPED",
      "synched": false
    }
  }
}

Step 3: Plan your Targeting

A line item can target content in several ways. Understanding the targeting model before creating the line item will save you time.

Content targeting: only your network

The most important constraint to understand is that content targeting only works for shows, episodes, and users that belong to your organization. You cannot target content from outside your network.

There are three content targeting fields:

  • target_user_ids — target all episodes from specific podcasters in your network
  • target_show_ids — target all episodes from specific shows
  • target_episode_ids — include or exclude specific individual episodes

These can be combined. For example, you can include an entire show but exclude one specific episode from it.

Ad type and position

Use target_ads_type to choose where in an episode the ad plays:

  • preroll — plays before the episode starts
  • midroll — plays during the episode
  • postroll — plays after the episode ends

If you include midroll, you can further restrict which midroll positions to use with target_midroll_position. Positions are numbered from 1 (the first midroll break) to 10.

Date and age filters

Two filters help you avoid serving ads against stale content:

  • target_content_pubdate — filter episodes by their original publication date
  • target_content_age — filter episodes by how many days old they are

Both support INCLUDE and EXCLUDE with LESS_OR_EQUAL and GREATER_OR_EQUAL matchers.

Geographic targeting

Use target_geo to restrict delivery to specific countries, regions, or DMAs. You can include a broad area and then exclude a subset of it. See Retrieving Available Targeting Countries for the full list of valid codes.

Delivery and pricing

  • goal_impressions — the total number of impressions to deliver
  • goal_pacing — PACED spreads delivery evenly across the flight dates, ASAP delivers as fast as possible
  • price_amount — CPM rate (cost per 1000 impressions)
  • priority_id — determines how this line item competes for ad slots against other line items. Higher priority wins over lower priority.
  • frequency_cap — limits how many times the same ad is served per download

Step 4: Find Content to Target

Before creating the line item you need the IDs of the shows or episodes you want to target. There are two ways to discover them.

Browse your network

To list all shows available within your organization:

curl -H "Authorization: Bearer OAUTH-TOKEN" \
  "https://api.spreaker.com/v2/users/USER-ID/shows?access_level=AUTHOR,SHOW_COLLABORATOR,USER_COLLABORATOR&filter=editable"

To list episodes of a specific show:

curl -H "Authorization: Bearer OAUTH-TOKEN" \
  "https://api.spreaker.com/v2/shows/SHOW-ID/episodes?filter=editable"

To list all podcasters (users with at least one podcast) in your network:

curl -H "Authorization: Bearer OAUTH-TOKEN" \
  "https://api.spreaker.com/v2/organizations/ORGANIZATION-ID/users?filter=network"

Search your network

If you know what you are looking for, use the organization-scoped search APIs:

# Search for shows
curl -H "Authorization: Bearer OAUTH-TOKEN" \
  "https://api.spreaker.com/v2/search/organizations/ORGANIZATION-ID?type=shows&q=QUERY"

# Search for episodes
curl -H "Authorization: Bearer OAUTH-TOKEN" \
  "https://api.spreaker.com/v2/search/organizations/ORGANIZATION-ID?type=episodes&q=QUERY"

# Search for podcasters
curl -H "Authorization: Bearer OAUTH-TOKEN" \
  "https://api.spreaker.com/v2/search/organizations/ORGANIZATION-ID?type=users&filter=network&q=QUERY"

For this guide, assume you found a show with show_id: 4117941 that you want to target, and one episode with episode_id: 19716642 that you want to exclude.

Step 5: Create the Line Item

You now have everything you need to create the line item. This example creates a line item that:

  • Belongs to the campaign created in Step 2
  • Targets preroll and midroll (positions 1 and 2) ad slots
  • Targets a specific show, excluding one episode
  • Only targets episodes published after 2025-01-01 and no older than 90 days
  • Targets listeners in the US, but excludes the Buffalo DMA
  • Delivers 10,000 impressions at a CPM of $12, paced evenly across the flight
curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" \
  -F "campaign_id=9036" \
  -F "name=Acme Summer - Show Targeting" \
  -F "audio_ad_file=@acme-summer-ad.mp3" \
  -F "active=false" \
  -F "start_date=2026-06-01 00:00:00" \
  -F "end_date=2026-08-31 23:59:59" \
  -F "goal_impressions=10000" \
  -F "goal_pacing=PACED" \
  -F "price_amount=12" \
  -F "priority_id=40" \
  -F 'frequency_cap=[{"type":"IMPS_PER_DOWNLOAD","value":1}]' \
  -F 'target_ads_type=[{"type":"INCLUDE","matcher":"ONE_OF","value":["preroll","midroll"]}]' \
  -F 'target_midroll_position=[{"type":"INCLUDE","matcher":"ONE_OF","value":["1","2"]}]' \
  -F 'target_show_ids=[{"type":"INCLUDE","matcher":"ONE_OF","value":[4117941]}]' \
  -F 'target_episode_ids=[{"type":"EXCLUDE","matcher":"ONE_OF","value":[19716642]}]' \
  -F 'target_content_pubdate=[{"type":"INCLUDE","matcher":"GREATER_OR_EQUAL","value":"2025-01-01"}]' \
  -F 'target_content_age=[{"type":"INCLUDE","matcher":"LESS_OR_EQUAL","value":"90"}]' \
  -F 'target_geo=[{"type":"INCLUDE","matcher":"EQUAL","value":{"country":"US","region":null,"subregion":null,"dma":null,"postalcodes":null}},{"type":"EXCLUDE","matcher":"EQUAL","value":{"country":"US","region":"NY","subregion":null,"dma":"514","postalcodes":null}}]' \
  https://api.spreaker.com/v2/lineitems

Save the lineitem_id from the response. Note that the line item is created with active=false — it will not deliver until you explicitly activate it in Step 7.

Step 6: Replace the Audio Creative

The audio creative is required at creation and was already included in Step 5. If you need to replace it later — for example to update a promotion or fix an error — send a new audio_ad_file to the update endpoint. The previous file will be replaced.

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" \
  -F "audio_ad_file=@acme-summer-ad-v2.mp3" \
  https://api.spreaker.com/v2/lineitems/LINEITEM-ID

Once processed, the response will include updated audio_ad_url and audio_ad_filename values. The audio_ad_file field itself is never returned in responses.

Step 7: Activate the Line Item

The line item is ready. Set active=true to allow delivery to begin. The ad server will start serving the ad as soon as the start_date is reached, as long as the line item and campaign are synched.

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" \
  -F "active=true" \
  https://api.spreaker.com/v2/lineitems/LINEITEM-ID

You can pause delivery at any time by setting active=false on the same endpoint.

Newly created line items and campaigns go through a background sync with the ad server before they can deliver. If the line item is active but not yet delivering, check the synched field on both the campaign and the line item — delivery will begin once both are true.