API: Line Items

In this page

The Line Item object

A Line Item defines the delivery rules, targeting, and pricing for an ad within a Campaign.

A line item has several properties. Each API can return a Line Item model in its entirety or with just a subset. All properties are listed here:

Property Type Description
lineitem_id Numeric Unique line item identifier
name String Required. Line item name
active Boolean Whether the line item is active
priority_id Numeric Required. Delivery priority. Possible values: 20 (Sponsorship), 30 (High), 40 (Medium), 50 (Low), 60 (Ad Exchange), 70 (Remnant)
start_date String Required. Delivery start date and time
end_date String Required. Delivery end date and time
audio_ad_url String URL of the ingested audio creative, or null if not yet uploaded
audio_ad_filename String Filename of the ingested audio creative, or null if not yet uploaded
campaign_id Numeric Required. ID of the Campaign this line item belongs to
campaign_name String Name of the campaign this line item belongs to
status String Line item status. Possible values: STOPPED, NOT_STARTED, RUNNING, COMPLETED
goal_pacing String Required. Impression delivery pacing. Possible values: PACED, ASAP
goal_impressions Numeric Required. Total impression goal
impressions_tracked Numeric Number of impressions delivered so far
price_type String Pricing model. Possible values: CPM
price_amount Numeric Required. Price per 1000 impressions (CPM)
team_id Numeric ID of the team this line item belongs to
third_party_impression_urls Array List of third-party impression tracking URLs. Max: 3
frequency_cap Array List of Frequency Cap objects
target_geo Array List of Targeting Filter objects for geographic targeting. See Available Targeting Countries
target_ads_type Array List of Targeting Filter objects for ad type. Only type: INCLUDE and matcher: ONE_OF are supported. Possible values: preroll, midroll, postroll
target_midroll_position Array List of Targeting Filter objects restricting which midroll positions to target (only applies when midroll is included in target_ads_type). Only matcher: ONE_OF is supported. Allowed positions: 1 to 10
target_user_ids Array List of Targeting Filter objects for user targeting. Only matcher: ONE_OF is supported
target_show_ids Array List of Targeting Filter objects for show targeting. Only matcher: ONE_OF is supported
target_episode_ids Array List of Targeting Filter objects for episode targeting. Only matcher: ONE_OF is supported
target_content_pubdate Array List of Targeting Filter objects for content publish date. Only matcher: LESS_OR_EQUAL and matcher: GREATER_OR_EQUAL are supported
target_content_age Array List of Targeting Filter objects for content age in days. Only matcher: LESS_OR_EQUAL and matcher: GREATER_OR_EQUAL are supported
target_category_ids Array List of Targeting Filter objects for category targeting. Only matcher: ONE_OF is supported. See List of Show Categories
synched Boolean true if the line item has been synched with the ad server, false otherwise
users Array Expanded User objects resolved from target_user_ids
shows Array Expanded Show objects resolved from target_show_ids
episodes Array Expanded Episode objects resolved from target_episode_ids
categories Array Expanded Category objects resolved from target_category_ids

Many of the resources on the line item APIs are related to a single line item. If a request URL includes LINEITEM-ID it refers to the numeric Line Item ID.

Targeting Filter objects

Targeting fields (e.g. target_geo, target_show_ids) are arrays of filter objects. Each filter object has three properties:

Property Type Description
type String Whether to INCLUDE or EXCLUDE the matched content
matcher String Matching strategy: EQUAL, ONE_OF, LESS_OR_EQUAL, GREATER_OR_EQUAL
value Mixed The value to match against. Type depends on the targeting field (string, number, array, or geo object)

Each targeting field only supports specific type and matcher combinations — see the individual field descriptions in The Line Item object for the constraints.

Multiple filter objects within the same field are evaluated together: INCLUDE filters define the allowed set, and EXCLUDE filters are then applied on top to narrow it down.

Target specific shows, exclude one:

"target_show_ids": [
  { "type": "INCLUDE", "matcher": "ONE_OF", "value": [4117941, 5231042] },
  { "type": "EXCLUDE", "matcher": "ONE_OF", "value": [5231042] }
]

Target episodes published after a date:

"target_content_pubdate": [
  { "type": "INCLUDE", "matcher": "GREATER_OR_EQUAL", "value": "2025-01-01" }
]

Target episodes no older than 90 days:

"target_content_age": [
  { "type": "INCLUDE", "matcher": "LESS_OR_EQUAL", "value": "90" }
]

Target preroll and midroll, positions 1 and 2 only:

"target_ads_type": [
  { "type": "INCLUDE", "matcher": "ONE_OF", "value": ["preroll", "midroll"] }
],
"target_midroll_position": [
  { "type": "INCLUDE", "matcher": "ONE_OF", "value": ["1", "2"] }
]

Geographic targeting

The target_geo value is an object with the following fields:

Property Type Description
country String ISO 3166-1 alpha-2 country code
region String Region/state code, or null
subregion String Subregion code, or null
dma String DMA (Designated Market Area) code, or null
postalcodes String Postal codes, or null

See Retrieving Available Targeting Countries for the full list of valid codes.

Target New York state, but exclude the Buffalo DMA:

"target_geo": [
  { "type": "INCLUDE", "matcher": "EQUAL", "value": { "country": "US", "region": "NY", "subregion": null, "dma": null, "postalcodes": null } },
  { "type": "EXCLUDE", "matcher": "EQUAL", "value": { "country": "US", "region": "NY", "subregion": null, "dma": "514", "postalcodes": null } }
]

Content targeting

target_user_ids, target_show_ids, and target_episode_ids can only reference content owned by or within your organization. Targeting content outside your network is not supported.

To discover valid IDs to use in these fields:

  • Users — list all podcasters in your network with GET /v2/organizations/ORGANIZATION-ID/users?filter=network, or search within the network with GET /v2/search/organizations/ORGANIZATION-ID?type=users&filter=network&q=QUERY.
  • Shows — list all shows in your network with Retrieve a User’s Shows using access_level=AUTHOR,SHOW_COLLABORATOR,USER_COLLABORATOR, or search with GET /v2/search/organizations/ORGANIZATION-ID?type=shows&q=QUERY.
  • Episodes — list episodes with Retrieve a User’s Episodes or Retrieve a Show’s Episodes using filter=editable, or search with GET /v2/search/organizations/ORGANIZATION-ID?type=episodes&q=QUERY.

Frequency Cap object

The frequency_cap field is an array of objects with the following structure:

Property Type Description
type String Cap type. Possible values: IMPS_PER_DOWNLOAD
value Numeric Maximum number of impressions per download

Retrieving the Line Item List

GET /v2/lineitems

Authenticated: yes

This API returns a paginated list of Line Items.

Parameter Type Description
campaign_id Numeric Filter line items by Campaign. If omitted, all line items in the organization are returned

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/lineitems?campaign_id=9036

The response body is a paginated list of Line Items.

{
  "response": {
    "items": [
      {
        "lineitem_id": 26130,
        "name": "Lineitem",
        "active": false,
        "priority_id": 50,
        "start_date": "2026-05-25 00:00:00",
        "end_date": "2026-06-30 00:00:00",
        "audio_ad_url": "https://d3ik3xd6ewakyc.cloudfront.net/media/29055_phpubeoi2qfevre5jMlocb.mp3",
        "audio_ad_filename": "29055_phpubeoi2qfevre5jMlocb.mp3",
        "campaign_id": 9036,
        "campaign_name": "New Campaign",
        "status": "STOPPED",
        "goal_pacing": "PACED",
        "goal_impressions": 1000,
        "impressions_tracked": 0,
        "price_type": "CPM",
        "price_amount": 10,
        "team_id": 59,
        "synched": false
      }
    ],
    "next_url": null,
    "prev_url": null
  }
}

Retrieving a Single Line Item

GET /v2/lineitems/LINEITEM-ID

Authenticated: yes

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/lineitems/26130

The response body is a JSON object containing all the line item fields, including expanded users, shows, episodes, and categories objects resolved from the targeting filters.

{
  "response": {
    "lineitem": {
      "lineitem_id": 26130,
      "name": "Lineitem",
      "active": false,
      "priority_id": 50,
      "start_date": "2026-05-25 00:00:00",
      "end_date": "2026-06-30 00:00:00",
      "audio_ad_url": "https://d3ik3xd6ewakyc.cloudfront.net/media/29055_phpubeoi2qfevre5jMlocb.mp3",
      "audio_ad_filename": "29055_phpubeoi2qfevre5jMlocb.mp3",
      "campaign_id": 9036,
      "campaign_name": "New Campaign",
      "status": "STOPPED",
      "goal_pacing": "PACED",
      "goal_impressions": 1000,
      "impressions_tracked": 0,
      "price_type": "CPM",
      "price_amount": 10,
      "team_id": 59,
      "third_party_impression_urls": ["https://tracking.com"],
      "frequency_cap": [
        { "type": "IMPS_PER_DOWNLOAD", "value": 1 }
      ],
      "target_geo": [
        {
          "type": "INCLUDE",
          "matcher": "EQUAL",
          "value": { "country": "US", "region": "NY", "subregion": null, "dma": null, "postalcodes": null }
        },
        {
          "type": "EXCLUDE",
          "matcher": "EQUAL",
          "value": { "country": "US", "region": "NY", "subregion": null, "dma": "514", "postalcodes": null }
        }
      ],
      "target_ads_type": [
        { "type": "INCLUDE", "matcher": "ONE_OF", "value": ["preroll", "midroll"] }
      ],
      "target_midroll_position": [
        { "type": "INCLUDE", "matcher": "ONE_OF", "value": ["1", "2"] }
      ],
      "target_user_ids": [
        { "type": "INCLUDE", "matcher": "ONE_OF", "value": [11685024] }
      ],
      "target_show_ids": [
        { "type": "INCLUDE", "matcher": "ONE_OF", "value": [4117941] }
      ],
      "target_episode_ids": [
        { "type": "EXCLUDE", "matcher": "ONE_OF", "value": [19716642] }
      ],
      "target_content_pubdate": [
        { "type": "EXCLUDE", "matcher": "LESS_OR_EQUAL", "value": "2026-01-01" }
      ],
      "target_content_age": [
        { "type": "EXCLUDE", "matcher": "GREATER_OR_EQUAL", "value": "200" }
      ],
      "target_category_ids": [
        { "type": "EXCLUDE", "matcher": "ONE_OF", "value": [93] }
      ],
      "synched": true,
      "users": [
        {
          "user_id": 11685024,
          "fullname": "The Slang Podcast",
          "site_url": "https://www.spreaker.com/user/the-slang-podcast--11685024",
          "image_url": "https://d3wo5wojvuv7l.cloudfront.net/t_square_limited_160/images.spreaker.com/original/7859e656495cb5b2fc49b343e93e2497.jpg",
          "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/7859e656495cb5b2fc49b343e93e2497.jpg"
        }
      ],
      "shows": [
        {
          "show_id": 4117941,
          "title": "The Slang Podcast - Learn British English Now",
          "site_url": "https://www.spreaker.com/podcast/the-slang-podcast-learn-british-english-now--4117941",
          "image_url": "https://d3wo5wojvuv7l.cloudfront.net/t_square_limited_160/images.spreaker.com/original/7859e656495cb5b2fc49b343e93e2497.jpg",
          "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/7859e656495cb5b2fc49b343e93e2497.jpg",
          "author_id": 11685024
        }
      ],
      "episodes": [
        {
          "episode_id": 19716642,
          "title": "Beef - What does \"Beef\" mean in British slang?",
          "show_id": 4117941,
          "author_id": 11685024,
          "site_url": "https://www.spreaker.com/episode/beef-what-does-beef-mean-in-british-slang--19716642"
        }
      ],
      "categories": [
        {
          "category_id": 93,
          "name": "Books",
          "permalink": "arts-books",
          "level": 2
        }
      ]
    }
  }
}

Creating a Line Item

POST /v2/lineitems

Authenticated: yes

Parameter Type Description
campaign_id Numeric Required. ID of the Campaign this line item belongs to
name String Required. Line item name
audio_ad_file File Required. The audio creative to ingest into the line item. Accepted format: MP3. Can be provided at creation or at any point later to replace the existing creative. This field is write-only — it is never returned in responses; use audio_ad_url and audio_ad_filename to retrieve the current creative
priority_id Numeric Required. Delivery priority. Possible values: 20 (Sponsorship), 30 (High), 40 (Medium), 50 (Low), 60 (Ad Exchange), 70 (Remnant)
start_date String Required. Delivery start date and time (YYYY-MM-DD HH:MM:SS)
end_date String Required. Delivery end date and time (YYYY-MM-DD HH:MM:SS)
goal_impressions Numeric Required. Total impression goal
goal_pacing String Required. Impression delivery pacing. Allowed: PACED, ASAP
price_amount Numeric Required. Price per 1000 impressions (CPM)
active Boolean Whether the line item is active (defaults to false)
third_party_impression_urls String Third-party impression tracking URL. Max: 3 URLs
frequency_cap JSON Array of Frequency Cap objects
target_geo JSON Array of Targeting Filter objects for geographic targeting
target_ads_type JSON Array of Targeting Filter objects for ad type. Only type: INCLUDE and matcher: ONE_OF are supported. Possible values: preroll, midroll, postroll
target_midroll_position JSON Array of Targeting Filter objects restricting midroll positions (only applies when midroll is in target_ads_type). Only matcher: ONE_OF is supported. Allowed positions: 1 to 10
target_user_ids JSON Array of Targeting Filter objects for user targeting. Only matcher: ONE_OF is supported
target_show_ids JSON Array of Targeting Filter objects for show targeting. Only matcher: ONE_OF is supported
target_episode_ids JSON Array of Targeting Filter objects for episode targeting. Only matcher: ONE_OF is supported
target_content_pubdate JSON Array of Targeting Filter objects for content publish date. Only matcher: LESS_OR_EQUAL and matcher: GREATER_OR_EQUAL are supported
target_content_age JSON Array of Targeting Filter objects for content age in days. Only matcher: LESS_OR_EQUAL and matcher: GREATER_OR_EQUAL are supported
target_category_ids JSON Array of Targeting Filter objects for category targeting. Only matcher: ONE_OF is supported. See List of Show Categories

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" \
  -F "campaign_id=9036" \
  -F "name=Lineitem" \
  -F "active=false" \
  -F "audio_ad_file=@ad.mp3" \
  -F "start_date=2026-05-25 14:00:00" \
  -F "end_date=2026-06-30 14:00:00" \
  -F "goal_impressions=1000" \
  -F "goal_pacing=PACED" \
  -F "price_amount=10" \
  -F "priority_id=50" \
  -F 'frequency_cap=[{"type":"IMPS_PER_DOWNLOAD","value":1}]' \
  -F 'target_ads_type=[{"type":"INCLUDE","matcher":"ONE_OF","value":["preroll","midroll"]}]' \
  -F 'target_geo=[{"type":"INCLUDE","matcher":"EQUAL","value":{"country":"US","region":"NY"}}]' \
  https://api.spreaker.com/v2/lineitems

The response body is a JSON object containing all the line item fields.

Updating a Line Item

POST /v2/lineitems/LINEITEM-ID

Authenticated: yes

The API POST /v2/lineitems/LINEITEM-ID supports all the parameters of Creating a Line Item, none of which are required, as you should specify only the ones you want to update.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" \
  -F "name=New Lineitem Name" \
  -F "goal_pacing=ASAP" \
  -F "goal_impressions=1000" \
  -F "price_amount=8" \
  https://api.spreaker.com/v2/lineitems/26130

The response body is a JSON object containing all the updated line item fields.

{
  "response": {
    "lineitem": {
      "lineitem_id": 26130,
      "name": "New Lineitem Name",
      "goal_pacing": "ASAP",
      "goal_impressions": 1000,
      "price_amount": 8,
      "synched": false,
      "..."
    }
  }
}

Cloning a Line Item

POST /v2/lineitems/LINEITEM-ID/clone

Authenticated: yes

Creates a copy of the line item. All targeting and settings are duplicated, but the audio ad file (audio_ad_url, audio_ad_filename) is not copied and must be uploaded separately on the clone.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/lineitems/26130/clone

The response body is a JSON object containing all the fields of the newly created line item. The clone’s name is prefixed with Copy of.

{
  "response": {
    "lineitem": {
      "lineitem_id": 26131,
      "name": "Copy of New Lineitem Name",
      "active": false,
      "audio_ad_url": null,
      "audio_ad_filename": null,
      "campaign_id": 9036,
      "synched": false,
      "..."
    }
  }
}

Deleting a Line Item

DELETE /v2/lineitems/LINEITEM-ID

Authenticated: yes

Example

curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/lineitems/26130

The response body is an empty object.

{ "response": [] }

Retrieving Available Targeting Countries

GET /v2/campaigns-countries

Authenticated: yes

Returns the full list of countries, regions, subregions, and DMAs available for use in target_geo targeting filters.

Each country entry has the following structure:

Property Type Description
code String ISO 3166-1 alpha-2 country code
name String Country name
regions Object Map of region code to region object (see below)

Each region object has:

Property Type Description
code String Region code
name String Region name
subregions Array List of subregion objects (may be empty)
dmas Array List of DMA objects (may be empty)

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/campaigns-countries

The response body is a JSON array of country objects.

{
  "response": [
    {
      "code": "US",
      "name": "United States",
      "regions": {
        "NY": {
          "code": "NY",
          "name": "New York",
          "subregions": [],
          "dmas": [
            { "code": "501", "name": "New York" },
            { "code": "514", "name": "Buffalo" }
          ]
        },
        "CA": {
          "code": "CA",
          "name": "California",
          "subregions": [],
          "dmas": [
            { "code": "803", "name": "Los Angeles" }
          ]
        }
      }
    },
    {
      "code": "CA",
      "name": "Canada",
      "regions": {
        "ON": {
          "code": "ON",
          "name": "Ontario",
          "subregions": [],
          "dmas": []
        }
      }
    }
  ]
}