Bumper Scores for Ad Buyers
Agencies, ad buyers and ad platforms can see the Bumper Scores podcasters have shared with them in two ways:
- In your browser, at dashboard.wearebumper.com/ad-buyer. No code and no Bumper account needed.
- Through the Bumper API, so your own systems can read the scores directly.
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:
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.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:
- In your browser, at dashboard.wearebumper.com/ad-buyer. No code and no Bumper account needed.
- Through the Bumper API, with the endpoints below.
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_ofbeside 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.