Skip to content

Bumper Scores for Ad Buyers

Agencies, ad buyers and ad platforms can see the Bumper Scores podcasters have shared with them in two ways:

Both use the same access key. This page explains how to get one, how to use the web page, and what the API returns, with example requests and responses.

Podcasters stay in control

A podcaster owns their data, including their Bumper Score. You will only ever see scores for shows whose podcasters have agreed to share them with you, and a podcaster can withdraw that permission at any time.

Getting access

Access is set up by the Bumper team. Email support@wearebumper.com and tell us:

  • who should hold the access key, and
  • which shows you would like scores for.

Once the podcasters involved have agreed to share, we send your access key through a secure, one-time link. Store it somewhere safe: it is shown once, and we cannot recover it for you. If a key is lost or exposed, contact us and we will replace it.

Viewing scores in your browser

Go to dashboard.wearebumper.com/ad-buyer and paste in your access key. You'll see every show shared with you and its latest Bumper Score, and you can filter the list by show title.

The page remembers your key on that device, so you only enter it once. On a shared computer, choose Sign out of this device when you're done.

Coming soon, the same page will also let you ask a podcaster to share a score for a show that isn't shared with you yet.

API basics

Base URL https://api.wearebumper.com/v1.4
Authentication Authorization: Bearer <your access key> on every request
Format JSON responses; all timestamps are UTC in ISO 8601
Rate limit Reads (GET): 60 requests per minute. Writes (POST, which ask a podcaster for a score or add a contact, coming soon): 10 per minute and 100 per day
Freshness Scores are recalculated several times a day

Two endpoints read scores and are normally used together:

  1. GET /shared/podcasts — the shows shared with you, with Apple Podcasts and Spotify ids so you can match them to records in your own system.
  2. GET /shared/bumper_scores — the latest Bumper Score for up to 100 of those shows at a time.

A third group, requesting a score, will let you ask a podcaster to share a show that is not yet shared with you. It is coming soon and not yet available.

List the shows shared with you

GET /shared/podcasts

Returns every show a podcaster has shared with you, and what they have shared.

Example request

curl https://api.wearebumper.com/v1.4/shared/podcasts \
  -H "Authorization: Bearer $BUMPER_API_KEY"

Example response

{
  "ad_buyer": {
    "name": "Example Media Agency"
  },
  "data": [
    {
      "podcast_id": "3f2b8c1e-7a4d-4e5f-9b6a-1c2d3e4f5a6b",
      "title": "The Example Show",
      "feed_url": "https://feeds.example.com/the-example-show",
      "artwork_url": "https://images.example.com/the-example-show.jpg",
      "apple_podcasts_ids": ["1234567890"],
      "spotify_show_ids": ["0AbCdEfGhIjKlMnOpQrStU"],
      "scopes": ["bumper_score"],
      "granted_at": "2026-10-26T14:00:00Z",
      "expires_at": "2027-01-19T00:00:00Z"
    },
    {
      "podcast_id": "8d41e7a0-52c3-4b1f-a0d9-6e7f8a9b0c1d",
      "title": "Another Example Show",
      "feed_url": "https://feeds.example.com/another-example-show",
      "artwork_url": null,
      "apple_podcasts_ids": ["1098765432"],
      "spotify_show_ids": [],
      "scopes": ["bumper_score"],
      "granted_at": "2026-10-28T09:30:00Z",
      "expires_at": null
    }
  ]
}

Fields

Field Description
podcast_id Bumper's id for the show. Use it to request scores.
title The show's title.
feed_url The show's RSS feed, when known. May be null.
artwork_url The show's cover art, when known. May be null.
apple_podcasts_ids The show's Apple Podcasts id(s). A list, because a show occasionally has more than one. May be empty.
spotify_show_ids The show's Spotify show id(s). A list for the same reason. May be empty.
scopes What the podcaster has shared with you. bumper_score means you can request this show's Bumper Score.
granted_at When the podcaster shared it.
expires_at When sharing stops, if the podcaster chose an end date. null when they set none. After this moment the show no longer appears in /shared/podcasts.

Matching shows to your own records

Apple Podcasts and Spotify ids are the most reliable way to match a Bumper show to a show in your own system. Store Bumper's podcast_id alongside your record once matched, and use it for every score request after that.

Get Bumper Scores

GET /shared/bumper_scores?podcast_id=<id>&podcast_id=<id>…

Returns the most recent Bumper Score for each show you ask for. Repeat the podcast_id parameter once per show, between 1 and 100 per request.

Example request

curl -G https://api.wearebumper.com/v1.4/shared/bumper_scores \
  -H "Authorization: Bearer $BUMPER_API_KEY" \
  --data-urlencode "podcast_id=3f2b8c1e-7a4d-4e5f-9b6a-1c2d3e4f5a6b" \
  --data-urlencode "podcast_id=8e7d6c5b-4a39-4281-b0f1-e2d3c4b5a697"

Example response

Each show you ask for gets exactly one entry, in the order you asked for them.

{
  "data": [
    {
      "podcast_id": "3f2b8c1e-7a4d-4e5f-9b6a-1c2d3e4f5a6b",
      "status": "scored",
      "reason": null,
      "bumper_score": 112,
      "as_of": "2026-10-31T06:10:00Z",
      "sources": {
        "playback_platforms": ["apple", "spotify", "youtube"],
        "hosting_downloads": true,
        "episodes_scored": 14
      }
    },
    {
      "podcast_id": "8e7d6c5b-4a39-4281-b0f1-e2d3c4b5a697",
      "status": "gathering",
      "reason": null,
      "bumper_score": null,
      "as_of": null,
      "sources": null
    }
  ]
}

Fields

Field Description
podcast_id The show, as you requested it.
status Whether a score is available. See Score statuses.
reason Why a show is unavailable. null for every other status.
bumper_score The score, a whole number from 0 to 200 where 100 is the median show. null unless status is scored. See what the score means.
as_of When this score was calculated.
sources What went into the score. null unless status is scored.
sources.playback_platforms Which platforms contributed verified audience: any of apple, spotify, youtube.
sources.hosting_downloads true when the show's hosting provider supplied download counts for the score.
sources.episodes_scored How many recent episodes the score is based on. Scores built on fewer episodes move around more.

Score statuses

status What it means What to do
scored A current score is available. Use it.
gathering The show is eligible, but we don't have enough data to score it yet. A score is on its way. Check again later.
unavailable A score can't be calculated right now. reason says why. See below. Waiting may or may not help.
not_found Either there is no show with this id, or it has not been shared with you. Check the id against /shared/podcasts.

When status is unavailable, reason is one of:

reason What it means
too_new The show launched within the last seven days. A score follows once it has some history.
inactive The show hasn't released an episode in about three months. A score returns once it publishes again.
unsupported_host The show's hosting provider doesn't report the per-episode download data a score needs.
no_episodes_with_apple_and_spotify None of the show's recent episodes have data from both Apple Podcasts and Spotify, which every scored episode needs.

The Bumper Score page explains these eligibility rules in full.

Request a score

Coming soon

Score requests are not live yet. We're publishing these endpoints ahead of launch so you can plan your integration. Until launch, every request below returns 404. Details may still change before then, and we'll update this page when they're available. To ask for a score in the meantime, email support@wearebumper.com.

If a show isn't shared with you yet, you can ask its podcaster to share it. You identify the show by its Apple Podcasts id, and we email the people you name and, where we can, the show's owners. We never tell you whether a show is on Bumper, and the responses below are the same either way.

You'll be able to ask in two ways, with the same access key:

Ask for a score

POST /shared/score_requests

Example request

curl -X POST https://api.wearebumper.com/v1.4/shared/score_requests \
  -H "Authorization: Bearer $BUMPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apple_podcasts_id": 1234567890,
    "podcast_title": "The Example Show",
    "to": ["host@example.com"],
    "from_name": "Pat Buyer",
    "brand": "Example Brand"
  }'
Field Description
apple_podcasts_id Required. The show's Apple Podcasts id, a positive whole number.
podcast_title Required. Up to 300 characters, on one line.
to Required. One to five email addresses to ask. Duplicates are ignored.
artwork_url Optional. An https:// link to the show's cover art.
from_name, brand, brand_contact Optional. Up to 100 characters each, on one line. Shown to the podcaster.
from_email, brand_email Optional. Email addresses.

Example response (201)

{
  "id": "5c0e2a7e-6f1c-4b8e-9d52-0a1b2c3d4e5f",
  "apple_podcasts_id": 1234567890,
  "podcast_title": "The Example Show",
  "artwork_url": null,
  "status": "requested",
  "brand": "Example Brand",
  "from_name": "Pat Buyer",
  "contacts": ["host@example.com"],
  "first_asked_at": "2026-11-07T15:00:00Z",
  "asked_at": "2026-11-07T15:00:00Z",
  "ask_count": 1,
  "can_ask_again_at": "2026-11-14T15:00:00Z"
}

You can ask about the same show again once seven days have passed since the last ask, up to five contact addresses in total.

List your requests

GET /shared/score_requests

Returns every request you have made, newest first, in a requests list of the objects above.

status What it means
requested The podcaster hasn't answered. can_ask_again_at says when you may ask again.
shared The podcaster shared the show with you. Read it from /shared/podcasts.
declined The podcaster said no. You can't ask about this show again.

can_ask_again_at is null unless status is requested. If the podcaster later stops sharing the show, or sharing reaches its end date, the request goes back to requested and you can ask again.

Check a show's hosting provider

GET /shared/score_requests/host_check?apple_podcasts_id=<id>

Before you ask, you can check whether the show's hosting provider supplies the data a Bumper Score needs. We read this from the show's public feed, so the answer says nothing about whether the show is on Bumper.

{"answer": "cant", "host": "Example Host"}
answer What it means
can The show's host can supply a score. A score also needs Apple Podcasts and Spotify data and recent episodes, so this isn't a promise.
cant The show's host doesn't report the per-episode downloads a score needs. You can still ask.
unknown We couldn't read the show's feed, or couldn't tell which host it uses.

host names the hosting provider when we recognise it, and is null otherwise.

Add a contact to a request

POST /shared/score_requests/{id}/contacts
curl -X POST https://api.wearebumper.com/v1.4/shared/score_requests/$REQUEST_ID/contacts \
  -H "Authorization: Bearer $BUMPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "producer@example.com"}'

Returns 204 with no body, whether or not the address was already on the request. Only the new address is emailed.

Request errors

Errors from these endpoints carry a detail object with a code:

HTTP status code When
409 too_soon You asked about this show within the last seven days. available_at says when you can ask again.
409 closed The request is shared or declined, so it can't be asked again or given another contact.
422 too_many_contacts The request would hold more than five addresses.

An unknown request id returns 404.

Errors

HTTP status When Response body
401 The access key is missing, invalid or has been revoked. {"detail": "Invalid or missing API key"}
422 A podcast_id isn't a valid id, or you sent none, or more than 100. A description of the invalid parameter
429 More than 60 GET requests in a minute, or more than 10 POST requests in a minute or 100 in a day. {"detail": "Rate limit exceeded. Retry in N seconds"}, with a Retry-After header giving N

If a show you were sharing with is no longer listed in /shared/podcasts, or a score request for it now returns not_found, sharing has ended. Either the podcaster has withdrawn access, or the end date they chose (the show's expires_at) has passed. The effect is the same either way, and the API doesn't tell you which.

Good practice

  • Fetch a few times a day, not on every page view. Scores change a few times a day at most, so store the latest one on your side and refresh it on a schedule.
  • Ask in batches. One request for 100 shows is far kinder to your rate limit than 100 requests for one.
  • Show the date. Displaying as_of beside a score tells your users how current it is.
  • Read the score as a benchmark. A Bumper Score compares a show with every other scored show, so it can move even when the show itself hasn't changed. A low score means less of a show's delivery can be independently verified, not that its audience isn't real. Read more about what the score does and doesn't tell you.

Questions? Contact us at support@wearebumper.com.