Ads API

The Spotify Ads API lets you build, manage, and report on Ad Studio campaigns. This guide can help you get started. Topics include:

• Getting started requirements and instructions
• An Ad Studio overview
• Descriptions of available endpoints
• Help and support information

If you're not sure what to do now, try these recommendations:

• New to the Ads API? See the Quick Start section. It provides instructions about how to set up an account to work with our API.

• Already using the Ads API? Great! Check the Release Notes section for information on the latest changes, or browse the available methods below.

To report a bug or ask questions about this service, contact the Ads API team at ads-api-support@spotify.com.

Sign up for our monthly Ads API newsletter here if you want to receive updates about new releases, testing opportunities, and more!

This section covers important design elements that affect how the Ads API works. Take a moment to review this information.

Rate limiting caps the number of API calls a user or app can make within a set period of time. The Ads API applies RPS rate limits on a per app basis for each client ID, regardless of the number of simultaneous app users. These limits help Spotify provide API access equitably to all our engineering partners.

Note: If our API returns status code 429, it means that you have sent too many requests. When this happens, check the Retry-After header, where you will see a number displayed. This is the number of seconds that you need to wait before you try your request again.

We have two types of rate limits per partner for production:

• per partner integration 50 rps (calculated in 30 second window)
• per IP 15 rps (calculated in 10 second window)

The most recent version of the Ads API is v2.

All endpoints are versioned with a version number in the URI. Version numbers are integers starting with a 1 or 2, and the version number is a prefix of the URI.

In accordance with semantic versioning, versions are bumped when there is a backwards-incompatible change that necessitates it. Major version releases are reserved for major API changes, such as complete revamping of our schemas or a new business model. Other than that, new fields, small schema changes etc fall under a minor change (such as 2.1).

Updates that do not break existing consumers will be deployed to the current version as patch releases.

Patch releases:

• Addition of new optional request body parameters to existing API methods
• Bug fixes that would not warrant a minor, or major release
• Changing the order of properties in existing API responses
• Documentation updates
• Testing improvements (e.g. more validation, coverage, etc.)
• Codebase improvements
• Addition of new endpoints

Minor releases, e.g. /v1.2/ to /v1.3/:

• Addition of new required request body parameters
• Default value is changed
• Deprecation of existing endpoints
• Deprecation of existing request body parameters
• Deprecation of URL path parameters
• Modification of response object

Major releases, e.g. /v1.2/ to /v2/:

• Modifying pre-existing request body parameters
• Modifying pre-existing URL path parameters
• Removing pre-existing endpoints

For each of these releases, the API team will communicate with clients and detail the changes in the API Release Notes.

We strongly recommend that you use the newest available version when upgrading your integration.

Times are always recorded in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ.

Some endpoints support a way of paging the dataset, taking an offset and limit as query parameters.

• limit specifies the number of results to be returned from the call. If not specified, the default value is 50. The max allowed value is also 50.
• offset specifies the starting position of the first result.

If you specify a limit of 5, the API will return 5 results. On the next page you’d put an offset of 6 to retrieve results 6 through 10. We return the total number of results along with the page size in the paging object.

This section documents changes made to the Spotify Ads API.

All of the following updates are included under a new major version (v2) released on August 8, 2023.

• The Campaign Management API is now generally available! These endpoints no longer require a manual allowlisting process to access.
• [Breaking Change] The following entities have been deprecated from the API:
  • advertiser: All references to advertiser, including advertiser endpoints, have been removed
  • organization: All references to organization have been removed
  • ad_set_links: All references to ad_set_links, including Ad Set Link endpoints, have been removed
• [Breaking Change] All resource names now follow snake_case convention (previously in v1, camelCase was used for path resources)
• [Breaking Change] All update requests now use the PATCH method to support partial data updates (previously in v1, PUT was used even though the resource is not fully replaced)

• [Breaking Change] page_size has been renamed to limit in all instances (previously in v1, both page_size and limit were used)
• [New] paging object is now returned if pagination is specified. Example:

• Endpoint to query a single ad account by ID called Get an Ad Account is now available
• Get Ad Accounts endpoint path has been shortened to GET /ad_accounts (was previously GET /currentUser/adAccounts)
• [Breaking Change] The following parameters have been deprecated from the ad account entity:
  • organization_id
  • ad_studio_lead
  • description
• [Breaking Change] The following parameters have been renamed under the ad account entity:
  • last_modified is now updated_at
  • iso_country_code is now country_code

• [New] The following parameters have been added to the campaign entity:
  • updated_at: When the campaign was last updated (read only)
  • purchase_order: Intended for organizational purposes; if specified, it will be displayed on invoices (optional for Create Campaign requests and cannot be updated)
  • objective: The objective of the campaign, previously referred to as bid_optimization_goal at the ad set level (required for Create Campaign requests and cannot be updated)
• [Breaking Change] The following parameters have been deprecated from the campaign entity:
  • description
  • advertiser_id
  • landing_page_domain
  • version
  • ad_set_ids
• [Breaking Change] The following endpoints have been deprecated:
  • Update Campaign Status
  • Get Campaigns (users can continue to call Get Campaigns by Ad Account ID and Get Campaigns by ID endpoints to retrieve campaigns)
• [Breaking Change] The following filters under Get Campaigns by Ad Account ID endpoint have been deprecated:
  • ids (ability to query by a single campaign ID still supported under Get Campaign by ID endpoint, but querying by an array of IDs is no longer supported)
  • advertiser_ids
  • statuses
  • name
• [Breaking Change] The following parameters have been renamed under the campaign entity:
  • created_on is now created_at

• [New] The following parameters have been added to the ad set entity:
  • updated_at: When the campaign was last updated (read only)
  • [Breaking Change] category: A category that most closely matches the content of the ad(s); certain categories may be subject to restrictions (required for Create Ad Set requests and can be updated)
  • podcast_episode_topics: Podcast episode topics to target (optional for Create Ad Set requests and can be updated)
  • sensitive_topic_exclusions: Sensitive podcast episode topics to exclude from ad placements (optional for Create Ad Set requests and can be updated)
  • language: Languages to target; languages are based on the language users use on Spotify (optional for Create Ad Set requests and cannot be updated)
  • interests: Interests to target; interests are based on listening habits and playlist preferences (optional for Create Ad Set requests and can be updated)
  • exclude_placements: When targeting a market where podcast ads are supported, placements will automatically default to include both podcast and music; users can set this parameter to PODCAST in order to limit their ad placement to music only (optional for Create Ad Set requests and can be updated)
  • delivery: Use to pause/resume ad set delivery; if set to ON, ad set will be served (once ad review is passed and start date occurs) and if set to OFF, ad set will not be served (optional for Create Ad Set requests and can be updated)
• [Breaking Change] The following parameters have been deprecated from the ad set entity:
  • advertiser_id
  • ad_ids (ability to link an ad to an ad set is still supported at the ad entity level)
  • active_status
  • ad_set_links
  • custom_audience_ids
  • serving_issues
  • version
• [Breaking Change] The following parameters have had schema changes or been renamed under the ad set entity:
  • targeting has been renamed to targets`
  • budget object added to the Create Ad Set request in order to match response schema:
    • budget_micro_amount in the Create Ad Set request is now nested under the budget object and renamed to micro_amount (previously budget_micro_amount was a root-level parameter)
    • type parameter has been added to specify a DAILY or LIFETIME budget (required for Create Ad Set requests)
    • country_code has been renamed to currency (read only)
  • Names of the following targeting parameters have been simplified:
    • gender_names is now genders
    • platform_names is now platforms
  • Geo targeting parameters (country_code, regions, dmas, cities, postal_codes) are now nested within a new - geo_targets object under targets
    • All geo target IDs are now string data type (previously they were integers [int32])
  • Metadata (e.g., name) is no longer returned with targeting parameters in Get Ad Set by Ad Account ID response – objects have been flattened into arrays where only the target ID(s) are included now
    • Metadata is still included in Get Ad Set by Ad Set ID response
  • artist_promotion has been renamed to promotion
    • name parameter under artist_promotion has been removed
    • artist_promotion_goal has been renamed to promotion_goal
    • Changes to the following promotion goal enum values:
      • ARTIST_CONTENT has been removed (artist targeting is now allowed for any ad set)
      • PODCAST_PROMO has been added (for promoting a podcast)
    • artist_promotion_target object has been removed and replaced with promotion_target_id parameter
  • bid_optimization_goal has been moved to the campaign entity level and renamed objective
  • format has been moved out of the targeting object and is now a root-level parameter, and has been renamed to - asset_format
• [Breaking Change] The following endpoints have been deprecated:
  • Update Ad Set Status (ability to update campaign status has been consolidated into Create and Update Ad Set endpoints in v2)
  • Get Ad Sets (users can continue to call Get Campaigns by Ad Account ID and Get Campaigns by ID endpoints to retrieve campaigns)
  • Get Ad Set Links
  • Get Ad Sets by Campaign
  • Update Ad Set Link Status
  • Get Ad Set Serving Status
• [Breaking Change] The following filters under Get Ad Sets by Ad Account ID endpoint have been deprecated:
  • ids (ability to query by a single ad set ID still supported under Get Ad Set by ID endpoint, but querying by an array of IDs is no longer supported)
    • advertiser_ids
    • campaign_ids
    • ad_ids
    • active_statuses
    • statuses
    • ad_stauses
    • name
• [Breaking Change] The following validation logic has been added:
  • Minimum budget amount
  • Minimum bid amount

• [New] The following parameters have been added to the ad entity:
  • updated_at: When the ad was last updated (read only)
  • call to action: The metadata for the behavior of the call-to-action button
    • text: The text used for the call-to-action button -- currently defaults to LEARN MORE but option to configure is coming soon (by end of August 2023)
    • clickthrough_url: The link to the ads desired landing page.
    • language: The language in which the call-to-action text is presented -- currently defaults to "ENGLISH" but option to configure is coming soon (by end of August 2023)
  • delivery: Use to pause/resume ad delivery; if set to ON, ad will be served (once ad review is passed and start date occurs) and if set to OFF, ad will not be served (optional for Create Ad requests and can be updated)
  • ad_preview_url: Link to view a preview of the ad
  • ad_set_id: The ID of the ad set to which the ad belongs
  • logo_image_asset: Part of assets object; logo image for the ad (optional for Create Ad requests and can be updated)
• [Breaking Change] The following parameters have been deprecated from the ad entity:
  • advertiser_id
  • landing_page_domain
  • version
• [Breaking Change] The following endpoints have been deprecated:
  • Get Ads (users can continue to call Get Ads by Ad Account ID and Get Ads by ID endpoints to retrieve campaigns)
• [Breaking Change] The following parameters have had schema changes or been renamed under the ad entity:
  • created has been renamed to created_at
  • brand_name has been renamed to advertiser_name
  • clickthrough_url is now nested under the call_to_action object
  • assets object has been simplified to contain the following parameters:
    • asset_id: ID of an audio or video asset (required on Create Ad requests and can be updated)
    • companion_asset_id: ID of a companion image asset (required on Create Ad requests and can be updated)
    • logo_asset_id: Nested under assets object - ID of a logo image asset (optional on Create Ad requests and can be updated)
  • third_party_viewability_tracking has been renamed to third_party_tracking and contains the following parameters:
    • measurement_partner: Name of the third-party measurement partner; DCM is now supported along with IAS
    • url: Third-party tracking URL
• [Breaking Change] The following filters have been deprecated under Get Ads by Ad Account ID endpoint:
  • ids (ability to query by a single ad ID still supported under Get Ad by ID endpoint, but querying by an array of IDs is no longer supported)
  • ad_set_ids
  • statuses
  • name

• [Breaking Change] Get Audio Assets, Get Video Assets, and Get Image Assets endpoints have been deprecated and replaced with a single endpoint called Get Assets by Asset Type and Ad Account
• [Breaking Change] Get Audio Asset, Get Video Asset, and Get Image Asset endpoints have been deprecated and replaced with a single endpoint called Get Asset
• [Breaking Change] Get Fullmix Upload Url, Get Video Upload Url, and Get Image Upload Url endpoints have been deprecated and replaced with a single Create Asset endpoint
• [New] The following endpoints have been added to enable asset upload:
  • Upload Asset: Upload image, audio, or video assets that are 25 MB or smaller
  • Start Upload Chunked Asset: Start a chunked upload session for image, audio, or video assets (required for files that are 25 MB or larger)
  • Transfer Chunked Asset: Continues the upload session of a chunked asset by transferring one section of binary media data
  • Complete Upload Chunked Asset: Completes the upload session of a chunked asset
• [New] Endpoint to update an asset called Update Asset is now available

• [New] Support for the following new targeting types has been added:
  • Postal codes: Postal code IDs can be retrieved via Get Geo Targets endpoint and input as an optional parameter in ‘targeting’ under ad sets entities
  • Interests: Interests can be retrieved via new endpoint Get Interest Targets and input as an optional parameter in ‘targeting’ under ad sets entities
  • Languages: Languages can be retrieved via new endpoint Get Language Targets and input as an optional parameter in ‘targeting’ under ad sets entities
  • Podcast episode topics: Only available for markets where podcast ads are supported – podcast episode topics can be retrieved via new endpoint Get Podcast Episode Targets and input as an optional parameter in ‘targeting’ under ad sets entities
  • Podcast sensitive episode topic exclusion: Only available for markets where podcast ads are supported – podcast sensitive episode topics can be retrieved via new endpoint Get Interest Targets and input as an optional parameter in ‘targeting’ under ad sets entities
• [Breaking Change] Consolidation of previous v1 targeting endpoints:
  • Get Artist Targets and Search Artist Targets have been consolidated into a single endpoint Get Artist Targets
  • Get Genre Targets and Search Genre Targets have been consolidated into a single endpoint Get Genre Targets
    • Querying by ids is no longer supported
  • Get Playlist Targets and Search Playlist Targets have been consolidated into a single endpoint Get Playlist Targets
    • Querying by ids is no longer supported
  • Get Geo Targets and Search Geo Targets have been consolidated into a single endpoint Get Geo Targets
    • New parameter parent_geo_name added to geo target entity
    • Renamed id and type parameters to geo_id and geo_type under geo target entity

• [Breaking Change] Create Report and Create Report by Ad Account have been deprecated and replaced with the following endpoints:
  • Get Aggregate Report by Ad Account Id: Returns aggregated ad campaign metrics based on requested fields and dimensions
  • Get Insight Report by Ad Account Id: Returns ad campaign metrics broken out by audience insights (e.g., age, gender, genre) based on requested fields – available only as ad set level breakdown at lifetime granularity and does not support report start/end time filtering
• [Breaking Change] The following dimensions values have been deprecated:
  • YEAR
  • MONTH
  • CURRENCY
  • COST_TYPE
  • ADVERTISER
  • DMA
  • REGION
• [Breaking Change] The following fields values have been deprecated:
  • FETCHES
  • RENDER_RATIO
  • FETCH_REACH
  • SERVES
  • ERRORS
  • COMPLETION_RATE
• [Breaking Change] The following fields have been renamed:
  • SERVE_REACH is now REACH
  • SERVE_FREQ is now FREQUENCY
• [Breaking Change] The following filters have been deprecated:
  • advertiser_ids
  • country_isos
  • region_ids
  • dma_ids
  • platforms
  • ad_set_start_dates
  • ad_set_end_dates
  • cost_type_filters
  • organization_ids
  • ad_account_ids (all reports must now include a single ad account ID in the path but filtering by multiple ad account IDs is no longer supported)
• [Breaking Change] Filtering by campaign, ad set, or ad ID(s) has been consolidated into two generic fields (previously this was supported via separate filters for each entity type):
  • entity_ids: A list of one or more campaign, ad set, or ad IDs by which to filter reporting
  • entity_ids_type: The entity type of IDs contained in the entity_ids field – if entity_ids is set, this field is required.
• [Breaking Change] Filtering by campaign, ad set, or ad ID status(es) has been consolidated into two generic fields:
  • entity_status_type: The entity type of statuses contained in the statuses field
  • statuses: A list of one or more campaign, ad set, or ad statuses by which to filter reporting – If this field is set, the entity_status_type field is required
• [New] The following audience insight dimensions have been added and are available under the Get Insight Report by Ad Account ID endpoint:
  • AGE
  • GENDER
  • GENRE
• [New] The following updates will go into effect on September 1, 2023:
  • Data refresh cadence will be increased to hourly (vs every few hours in v1-v1.4) – this will result in a discrepancy between UI and API stats for those who have not yet updated their integration to v2
  • Zero-stat campaigns (i.e., campaigns that have not yet been trafficked) will automatically be included in reports
  • SPEND field will be capped based on billable impressions; this means that spend tied to delivery over the specified budget will now be filtered out in order to match the UI’s logic
  • Support for report start/end filtering on LIFETIME granularity reports (upon initial Aug 8th v2 launch, report start/end filtering will only be available for HOUR or DAY granularity)

• Estimate Bid (formerly known as Get Bid Estimate)
  • [Breaking Change] Get Bid Estimate endpoint has been shortened to POST /estimates/bid (was previously POST /adAccounts/{ad_account_id}/estimate/bid)
  • [Breaking Change] budget_micro_amount is no longer required in the request body
  • [Breaking Change] The following parameters are now required when fetching a bid estimate:
    • start_date
    • end_date
    • asset_format
    • bid_strategy
    • currency
  • [Breaking Change] bid_optimization_goal has been renamed to objective
  • [New] The following optional request body parameters have been added:
    • frequency_caps
    • Under targets object:
      • postal_code_ids (nested under geo_targets)
      • podcast_episode_topic_ids
      • sensitive_topic_exclusion_ids
      • language
      • interest_ids
      • exclude_placements
• Estimate Audience (formerly known as Get Audience Estimate)
  • [Breaking Change] Get Bid Estimate endpoint has been shortened to POST /estimates/audience (was previously POST /adAccounts/{ad_account_id}/estimate/audience)
  • [Breaking Change] ad_account_id is now a request body parameter (was previously a path parameter)
  • [Breaking Change] The following parameters are now required when fetching a bid estimate:
    • start_date
    • end_date
    • asset_format
    • bid_strategy
    • budget (type & micro_amount)
  • [Breaking Change] bid_optimization_goal has been renamed to objective
  • [New] The following optional request body parameters have been added:
    • frequency_caps
    • Under targets object:
      • postal_code_ids (nested under geo_targets)
      • podcast_episode_topic_ids
      • sensitive_topic_exclusion_ids
      • language
      • interest_ids
      • exclude_placements
  • [New] The following parameters have been added to the response body:
    • estimated_frequency_min
    • estimated_frequency_max
    • forecast_type: The time granularity of the forecast -- if a "LIFETIME" budget type is specified, the API will return a single "LIFETIME" forecast type and if a "DAILY" budget type is specified, the API will return "DAILY", "WEEKLY" and "MONTHLY" forecast types
    • likely_to_deliver_budget: Indicates the likelihood of spending most of the budget

• Get Ad Categories endpoint: Ad categories can be retrieved via this endpoint and input under the ad_category parameter in the Create Ad Set request

• Get Podcast Shows endpoint: Available for podcast promotion use only (not for targeting) – podcast shows can be retrieved via this endpoint and input under the promotion_target_id parameter in the Create Ad Set request

• Now that the Campaign Management API is in GA, mention of manual allowlisting process and closed beta requirements have been removed
• Versioning policy has been simplified and schedule has been updated to reflect November 6, 2023 deprecation date for v1.3-v1.4
• Filtering and Querying section has been removed
• Slicing section has been removed
• Object Hierarchy has been updated to reflect v2 changes
• Build a Campaign Guide has been updated based on new v2 specs
• Metrics Glossary has been updated to only reflect metrics included in v2

All of the following updates are included under a new minor version (v1.4) released on November 29, 2022.

What's New

• Introducing new Click objective with accompanying Call-to-Action (“CTA”) card format
  • Spotify Ad Studio advertisers are now able to set up a click optimization goal for their campaigns along with reach and impressions goals introduced this year. Ads with click goal will be accompanied by a Call-to-Action card: a clickable ad experience consisting of an advertiser's companion image, a name and a call-to-action button. After the initial ad is served, the message will resurface across the Spotify app making it easier for listeners to remember and take action.
  • New enum value CLICKS is available under the bid_optimization_goal parameter when creating an ad set, updating an ad set, and retrieving bid/audience estimates
  • CTA cards will be enabled for music ads only (not video) – create ad endpoint now includes:
    • New required parameter brand_name: Displayed in ad
    • New optional parameter tagline: Displayed in CTA card, max 140 characters
    • These two parameters are included in the response when retrieving ads
  • Enforcing new validation logic, see Breaking Changes/Deprecations section below for details

Breaking Changes/Deprecations

• New parameter brand_name is now required when creating an ad
• Removed and replaced slot_type with format under ad sets/estimates targeting object
• Removed country_codes (array of string) under ad sets/estimates targeting object and replaced with country_code (string)
• Validation rules added:
  • Ad set start and end dates must be in the future
  • Max ad set duration of 365 days
  • Minimum length of 2 characters and maximum of 120 characters for campaigns, ad sets and ads entity names
  • Only one country may be targeted per ad set

All of the following updates are included under the current version of the API v1.3:

• New enum value ARTIST_CONTENT is available under the artist_promotion_goal parameter when creating an ad set or updating an ad set: Users can now specify when they are promoting an artist's merch or concert by selecting this option (NOTE: ARTIST_BOOST should continue to be used when promoting an artist's music on Spotify).

All of the following updates are included under a new minor version (v1.3) released July 2022.

What's New

• New minor version v1.3 released. Note: v1.1 and v1.2 will be fully deprecated on August 25, 2022. See Versioning section for version schedules.
• Addition of effective cost per mille and completed listen fields, ECPM and ECPCL, to reporting endpoints. See Metrics Glossary for detailed definitions.
• Ad sets and Estimates requests have been updated to use an auction pricing model, see "Breaking Changes/Deprecations" below for details
• frequency_caps is no longer a required parameter for create ad sets requests; it is now optional. If frequency_caps is not specified, API will default to the maximum allowed values:
  • 5 per day
  • 35 per week
  • 50 per month

Breaking Changes/Deprecations

• Addition of bid_optimization_goal, bid_strategy, and bid_micro_amount to ad sets output responses, as required fields to create ad sets requests, and as optional fields to update ad sets requests
  • Allowed values for bid_optimization_goal are:
    • EVEN_IMPRESSION_DELIVERY: We’ll aim to deliver as many impressions as possible to your target audience. Not available for active audio (CPCL) ad sets.
    • REACH: We’ll aim to reach as many unique listeners as possible with your message.
    • AD_COMPLETES: We’ll aim to deliver as many impressions as possible to your target audience. Available for active audio (CPCL) ad sets only.
  • Allowed values for bid_strategy are:
    • MAX_BID: The bid you specify will act as a ceiling/cap.
• The following fields under the ad sets objects have been renamed:
  • optimization is now artist_promotion
  • optimization_goal is now artist_promotion_goal
  • optimization_target is now artist_promotion_target
  • optimization_target_type is now artist_promotion_target_type
• The previous /estimate endpoints are deprecated and replaced with two new ones (Get Bid Estimate and Get Audience Estimate) that allow users to specify bid details:
  • POST /v1.3/adAccounts/{ad_account_id}/estimate/audience is replacing POST /v1.2/estimate
  • POST /v1.3/adAccounts/{ad_account_id}/estimate/bid is replacing POST /v1.2/adAccounts/{ad_account_id}/estimate/cost

Documentation Updates

• Migrated documentation to main portal Spotify for Developers

All of the following updates are included under a new minor version (v1.2) released December 2021.

What's New

• New minor version v1.2 released
• Added new pricing estimate endpoint to estimate your CPM/CLCL/CPCV based on specified targeting parameters
  • POST /adAccounts/{ad_account_id}/estimate/cost
• Added custom_audience_ids under the targeting parameter for ad sets
  • You now have the option to specify custom audiences to target when creating/updating an ad set
• Added third_party_viewability_tracking for ads
  • You now have the ability to set up third-party viewability tracking when creating/updating an ad
  • NOTE: This is currently only supported for measurement partner IAS

Breaking Changes/Deprecations

• “Flights” have been renamed “Ad Sets”
  • We have renamed all instances of these entities in v1.2 in order to match the nomenclature used in the Ad Studio UI
• “Creatives” have been renamed “Ads”
  • We have renamed all instances of these entities in v1.2 in order to match the nomenclature used in the Ad Studio UI
• Removed parameter “unit_cost_micro_amount” from Create Ad Set and Update Ad Set (fka Flight) endpoints

Documentation Updates

• Added new sections: “Metrics Glossary” and “Release Notes”
• Added additional detail on the expected behavior of the report_datetime_range filter under the Reporting API
• Updates to “Versioning” section - added version release/sunset schedule

• Added support for podcast ad performance data to the Reporting API
  • Ads served to podcast listeners on Spotify will automatically be reflected without making any updates to your integration
  • To capture the impressions served off Spotify, you will need to update your integration by adding the new metric called OFF_SPOTIFY_IMPRESSIONS
  • There are no breaking changes associated with this launch, however, we recommend that you complete this update as soon as possible in order to accurately reflect podcast ad performance

v1.1 was released June 2019

What's New

• Combined the /geo and /geos endpoints into just /geos. See docs here
• /geos endpoint now allows you to specify a type of geo you are searching for as a filter in a query param.

• Renamed the landing_page_url field to be landing_page_domain so it is consistent across the API
• Renamed arrays on GET targets and GET campaigns to be consistent with rest of API
• Refactored statuses on flight endpoint
• Pausing status for flight and flight links
  • Previously, you had to pause a flight on the update flight request. Now, there is a separate endpoint to pause / activate / archive a flight. You are no longer able to change the status on the update flight request.
• Added Flight Links endpoints
  • Flight links are a connection between flights and creatives that ensure the creative(s) and its contents are compatible with the flight’s targeting
• Added serving status endpoint
  • The new serving status endpoint indicates whether your flight is serving or not

• Added Campaign Status Endpoint
  • The available statuses for campaigns are ACTIVE, PAUSED, and ARCHIVED
• Removed CANCELLED as a status on campaigns
  • Campaigns can now only be archived, not cancelled
  • Archiving will permanently pause a campaign, you cannot unarchive a campaign
  • Archiving a campaign will prevent delivery across all associated flights
• Removed ability to update campaign status on PUT
  • Use the campaign status endpoint
• Added support for slicing on all GET LIST requests for creatives, flights, and campaigns
  • Slicing is the ability to specify what fields you want returned
  • How it works: GET LIST endpoints, there is a query parameter called fields where you can specify a comma-separated list of fields you want returned
• Added support for filtering on all the GET LIST requests for creatives, flights, and campaigns
  • Filtering is the ability to filter your results based on specific criteria (e.g., Get Flights for a specific Advertiser ID)
  • How it works: On the GET LIST endpoints, there are optional query parameters to specify the filter
• Added support for ordering by a specific field on GET LIST requests for creatives, campaigns, and flights
  • How it works: There are optional query parameters to specify the ordering field, ascending or descending based on the field