API Documentation - Sponsorable

Overview

API access is included with every paid plan. Create an API key from your account settings and start querying sponsors, contacts, podcasts, categories, and your lists.

Base URL

https://app.sponsorable.com/api/v1

The pre-versioned /api/sponsors routes continue to work as aliases of /api/v1/sponsors.

Authentication

The Sponsorable API uses Bearer token authentication. Include your API key in the Authorization header of every request.

HTTP Header

Authorization: Bearer YOUR_API_KEY

You can obtain an API key from your account settings. Keep your API key secure and never expose it in client-side code or public repositories.

Keep your API key secret. Your API key provides access to your account data. Do not share it in publicly accessible areas such as GitHub or client-side code.

Example Request

curl

curl https://app.sponsorable.com/api/v1/sponsors \
  -H "Authorization: Bearer YOUR_API_KEY"

Credits

Contact data follows the same rules as the Sponsorable app:

Starter — revealing a contact costs 1 credit from your monthly allowance. Locked contacts come back masked to initials ("J. D.") with disclosure fields (has_email, email_domain, has_linkedin) so you can decide before spending. Reveals are per-organization and permanent — you're never charged twice for the same contact.
Pro — contact data is unlimited and always returned unmasked.

Reads never spend credits. Only the explicit reveal endpoint charges. When your balance runs out, reveals return 402 Payment Required with your remaining balance.

Rate Limiting

The API enforces rate limits to ensure fair usage and maintain service stability. Rate limits are applied per organization.

Per minute	100 requests (rolling 60-second window)
Per day	2,000 requests (UTC calendar day)

When you exceed either limit, the API returns a 429 Too Many Requests response with information about when you can retry.

Rate Limit Exceeded Response 429

{
  "error": "Rate limit exceeded",
  "retry_after": 45,
  "retry_at": "2025-11-23T21:15:00Z"
}

Exceeding the daily limit returns the same shape with "error": "Daily request limit exceeded" and a retry_at of the next UTC midnight. Both responses include a Retry-After HTTP header indicating the number of seconds to wait before making another request.

Search endpoints also cap pagination depth at page 20; requests for deeper pages return 400 Bad Request. Narrow your filters instead of paging deep — if your use case genuinely needs more, contact us.

Errors

The Sponsorable API uses conventional HTTP response codes to indicate the success or failure of requests.

Code	Description
`200`	Success - The request completed successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`402`	Payment Required - Not enough credits (response includes `credits_remaining`)
`403`	Forbidden - Your plan doesn't include this (API access, podcasts, or reveals)
`404`	Not Found - The requested resource doesn't exist
`409`	Conflict - The item is already in the list
`429`	Rate Limited - Too many requests
`500`	Server Error - Something went wrong on our end

Error Response Format

Error responses include an error field describing what went wrong:

Authentication Error 401

{
  "error": "Invalid API token"
}

GET /api/v1/sponsors

List Sponsors

Returns a paginated list of sponsors matching your search criteria. Use query parameters to filter and search the sponsor database.

Each row includes a representative contact. On Starter the contact is masked (last name reduced to an initial, email withheld) with contact_email_available indicating whether an email exists — use the contacts endpoint to see all contacts and reveal the ones you want.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number for pagination (max 20). Default: `1`
`limit`	integer	Results per page (max 100). Default: `50`
`search`	string	Full-text search by sponsor name
`category`	string	Filter by category slug (e.g., `technology`, `business`, `comedy`)
`industry`	string	Filter by industry name. Values must be lowercase and URL encoded (e.g., `computer%20software`, `marketing%20%26%20advertising`)
`last`	string	Filter by last sponsorship recency: `day`, `week`, `month`, or `quarter`
`podcasts`	integer	Minimum number of podcasts sponsored (1-1,000,000)
`sponsorships`	integer	Minimum number of total sponsorships (1-1,000,000)
`podcast_sponsored`	string	Filter to sponsors of a specific podcast (by podcast ID)

Example Request

curl

curl "https://app.sponsorable.com/api/v1/sponsors?page=1&limit=25&search=shopify&category=technology" \
  -H "Authorization: Bearer YOUR_API_KEY"

HTTP

GET /api/v1/sponsors?page=1&limit=25&search=shopify&category=technology HTTP/1.1
Host: app.sponsorable.com
Authorization: Bearer YOUR_API_KEY

Response

Response 200

{
  "data": [
    {
      "domain": "shopify.com",
      "name": "Shopify",
      "sponsorships": 842,
      "podcasts": 215,
      "last_sponsorship": "2025-11-20",
      "last_podcast": "How I Built This",
      "industry": "Software",
      "city": "Ottawa",
      "state": "ON",
      "country": "Canada",
      "employees": 10000,
      "description": "Shopify is a commerce platform that allows anyone to set up an online store...",
      "keywords": ["ecommerce", "saas", "retail"],
      "contact_title": "Director of Partnerships",
      "contact_email": "partnerships@shopify.com",
      "contact_email_available": true,
      "contact_first_name": "Jane",
      "contact_last_name": "Smith"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_results": 1,
    "per_page": 25
  }
}

Response Fields

Field	Type	Description
`domain`	string	Company domain (unique identifier)
`name`	string	Company/sponsor name
`sponsorships`	integer	Total number of sponsorships
`podcasts`	integer	Number of unique podcasts sponsored
`last_sponsorship`	string	ISO 8601 date of most recent sponsorship
`last_podcast`	string	Name of most recently sponsored podcast
`industry`	string	Industry category
`city`	string	Headquarters city
`state`	string	Headquarters state/province
`country`	string	Headquarters country
`employees`	integer	Employee count
`description`	string	Company description
`keywords`	array	Technology/business keywords
`contact_title`	string	Contact person's job title
`contact_email`	string\|null	Contact person's email (`null` on Starter until revealed)
`contact_email_available`	boolean	Whether an email exists for the representative contact
`contact_first_name`	string	Contact person's first name
`contact_last_name`	string	Contact person's last name (initial only on Starter, e.g. `"S."` — the first name is an initial too)

GET /api/v1/sponsors/:domain

Get Sponsor

Retrieves detailed information about a specific sponsor, including their top podcasts, categories, and recent sponsorship activity.

Path Parameters

Parameter	Type	Description
`domain`	string	The sponsor's domain (e.g., `shopify.com`)

Example Request

curl

curl https://app.sponsorable.com/api/v1/sponsors/shopify.com \
  -H "Authorization: Bearer YOUR_API_KEY"

HTTP

GET /api/v1/sponsors/shopify.com HTTP/1.1
Host: app.sponsorable.com
Authorization: Bearer YOUR_API_KEY

Response

Response 200

{
  "sponsor": {
    "domain": "shopify.com",
    "name": "Shopify",
    "description": "Shopify is a commerce platform that allows anyone to set up an online store...",
    "industry": "Software",
    "keywords": ["ecommerce", "saas", "retail"],
    "city": "Ottawa",
    "state": "ON",
    "country": "Canada",
    "employee_count": 10000,
    "sponsorships": 842,
    "podcasts": 215,
    "repeat_podcasts": 89,
    "last_sponsorship_at": "2025-11-20",
    "linkedin_url": "https://linkedin.com/company/shopify",
    "x_url": "https://x.com/shopify",
    "facebook_url": "https://facebook.com/shopify",
    "contacts": 12
  },
  "top_podcasts": [
    {
      "podcast_id": "podcast_abc123",
      "name": "How I Built This",
      "sponsorships": 48,
      "first_sponsorship": "2021-03-15",
      "last_sponsorship": "2025-11-15"
    },
    {
      "podcast_id": "podcast_def456",
      "name": "The Tim Ferriss Show",
      "sponsorships": 36,
      "first_sponsorship": "2020-08-22",
      "last_sponsorship": "2025-10-28"
    }
  ],
  "top_categories": [
    {
      "slug": "business",
      "name": "Business",
      "sponsorships": 312
    },
    {
      "slug": "technology",
      "name": "Technology",
      "sponsorships": 245
    }
  ],
  "new_podcasts": [
    {
      "podcast_id": "podcast_ghi789",
      "name": "Startup Stories",
      "sponsorships": 2,
      "first_sponsorship": "2025-10-01",
      "last_sponsorship": "2025-11-01"
    }
  ]
}

Response Fields

Sponsor Object

Field	Type	Description
`domain`	string	Company domain (unique identifier)
`name`	string	Company/sponsor name
`description`	string	Company description
`industry`	string	Industry category
`keywords`	array	Technology/business keywords
`city`	string	Headquarters city
`state`	string	Headquarters state/province
`country`	string	Headquarters country
`employee_count`	integer	Number of employees
`sponsorships`	integer	Total sponsorships
`podcasts`	integer	Unique podcasts sponsored
`repeat_podcasts`	integer	Podcasts sponsored multiple times
`last_sponsorship_at`	string	ISO 8601 date of most recent sponsorship
`linkedin_url`	string\|null	LinkedIn company URL
`x_url`	string\|null	X (Twitter) URL
`facebook_url`	string\|null	Facebook URL
`contacts`	integer	Number of contacts in database

Top Podcasts & New Podcasts Arrays

Each array contains up to 5 podcast objects:

Field	Type	Description
`podcast_id`	string	Podcast identifier
`name`	string	Podcast name
`sponsorships`	integer	Number of sponsorships on this podcast
`first_sponsorship`	string	ISO 8601 date of first sponsorship
`last_sponsorship`	string	ISO 8601 date of most recent sponsorship

Top Categories Array

Contains up to 5 category objects:

Field	Type	Description
`slug`	string	Category slug
`name`	string	Category name
`sponsorships`	integer	Number of sponsorships in this category

Errors

Sponsor Not Found 404

{
  "error": "Sponsor not found"
}

GET /api/v1/sponsors/:domain/contacts

Get Sponsor Contacts

Returns all known contacts at a sponsor, ordered by how likely each is to own the podcast advertising budget. This endpoint never spends credits — on Starter, contacts you haven't revealed come back locked and masked, with disclosure fields showing what a reveal buys.

Example Request

curl

curl https://app.sponsorable.com/api/v1/sponsors/shopify.com/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Response (Starter, locked contact) 200

{
  "data": [
    {
      "contact_id": "633ed132-02d1-46dd-be4c-11d861a3fe78",
      "domain": "shopify.com",
      "name": "J. S.",
      "title": "Director of Partnerships",
      "location": "Ottawa, ON, Canada",
      "is_agency": false,
      "locked": true,
      "has_email": true,
      "email_domain": "shopify.com",
      "has_linkedin": true,
      "email": null,
      "linkedin_url": null
    }
  ]
}

Response Fields

Field	Type	Description
`contact_id`	string	Contact identifier — used to reveal
`name`	string	Full name (initials only while locked, e.g. `"J. S."`)
`title`	string	Job title (always visible)
`locked`	boolean	Whether a reveal is required for email/LinkedIn
`has_email`	boolean	Whether we have an email for this contact
`email_domain`	string\|null	Domain of the email (all contacts are in-house)
`has_linkedin`	boolean	Whether we have a LinkedIn profile URL
`email`	string\|null	Email address (`null` while locked)
`linkedin_url`	string\|null	LinkedIn profile URL (`null` while locked)

POST /api/v1/sponsors/:domain/contacts/:contact_id/reveal

Reveal Contact

Spends 1 credit (Starter) to unlock a contact's email and LinkedIn for your entire organization, permanently. Idempotent — revealing an already-unlocked contact returns it without charging again. If we don't have an email for the contact yet, revealing triggers an immediate email search and the address appears on the contact shortly after, at no extra cost.

Example Request

curl

curl -X POST \
  https://app.sponsorable.com/api/v1/sponsors/shopify.com/contacts/633ed132-02d1-46dd-be4c-11d861a3fe78/reveal \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Response 200

{
  "contact": {
    "contact_id": "633ed132-02d1-46dd-be4c-11d861a3fe78",
    "domain": "shopify.com",
    "name": "Jane Smith",
    "title": "Director of Partnerships",
    "locked": false,
    "email": "jane.smith@shopify.com",
    "linkedin_url": "https://linkedin.com/in/janesmith"
  },
  "credits_remaining": 87
}

Out of Credits 402

{
  "error": "Insufficient credits",
  "credits_remaining": 0
}

credits_remaining is null on Pro (unlimited).

GET /api/v1/podcasts

List Podcasts Pro plan

Search the podcast database. Available on the Pro plan (matching the podcasts section in the app); other plans receive a 403.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (max 20). Default: `1`
`limit`	integer	Results per page (max 100). Default: `50`
`search`	string	Full-text search across podcast name and description
`category`	string	Filter by category slug (same values as sponsors)
`industry`	string	Only podcasts sponsored by companies in this industry
`last`	string	Last episode recency: `day`, `week`, `month`, or `quarter`
`sponsors`	integer	Minimum number of unique sponsors
`sponsorships`	integer	Minimum number of total sponsorships
`episodes`	integer	Minimum number of episodes
`sort_by`	string	`episodes`, `sponsors`, `sponsorships`, or `last_episode`. Default: `sponsors`
`sort_order`	string	`asc` or `desc`. Default: `desc`

Response

Response 200

{
  "data": [
    {
      "podcast_id": "a03b138c-8b42-43bb-94a4-f2c9c45e289b",
      "name": "How I Built This",
      "description": "Stories behind the companies you know...",
      "website_url": "https://example.com",
      "categories": ["Business", "Entrepreneurship"],
      "episodes": 512,
      "last_episode_at": "2025-11-20",
      "sponsorships": 1204,
      "unique_sponsors": 87,
      "repeat_sponsors": 41,
      "last_sponsorship_at": "2025-11-20",
      "image_url": "https://cdn.sponsorable.com/podcasts/a03b138c-....jpg"
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 42, "total_results": 2071, "per_page": 50 }
}

GET /api/v1/podcasts/:podcast_id

Get Podcast Pro plan

The podcast's full profile, including the host/author name and email, plus its top sponsors and newest sponsors.

Response

Response 200

{
  "podcast": {
    "podcast_id": "a03b138c-8b42-43bb-94a4-f2c9c45e289b",
    "name": "How I Built This",
    "author_name": "Guy Raz",
    "author_email": "host@example.com",
    "categories": ["Business"],
    "episodes": 512,
    "sponsorships": 1204,
    "unique_sponsors": 87,
    "last_episode_at": "2025-11-20",
    "last_sponsorship_at": "2025-11-20",
    "image_url": "https://cdn.sponsorable.com/podcasts/a03b138c-....jpg"
  },
  "top_sponsors": [
    {
      "domain": "shopify.com",
      "name": "Shopify",
      "industry": "Computer Software",
      "country": "Canada",
      "sponsorships": 48,
      "first_sponsorship_at": "2021-03-15",
      "last_sponsorship_at": "2025-11-15"
    }
  ],
  "newest_sponsors": [ ... ]
}

GET /api/v1/categories

List Categories

The full category tree — 19 root categories with their children — with podcast, episode, sponsor, and sponsorship totals for each.

Response

Response 200

{
  "data": [
    {
      "category_id": "9c60…",
      "slug": "business",
      "name": "Business",
      "podcasts": 41230,
      "episodes": 812044,
      "sponsors": 18077,
      "sponsorships": 402188,
      "sponsored_podcasts": 9922,
      "sponsored_episodes": 160021,
      "children": [
        { "slug": "entrepreneurship", "name": "Entrepreneurship", ... }
      ]
    }
  ]
}

GET /api/v1/categories/:slug

Get Category

Category totals plus its top 10 sponsors and top 10 sponsored podcasts, each with sponsorship counts and first/last sponsorship dates.

Lists

Your organization's lists — the same lists as in the app, so items added via the API appear there immediately and can drive email alerts.

Endpoint	Description
`GET /api/v1/lists`	All lists with per-type item counts
`POST /api/v1/lists`	Create a list. Body: `name`
`GET /api/v1/lists/:list_id`	List detail with full item data — sponsors, podcasts, categories, and contacts (contacts are locked/masked per your plan, same as everywhere else)
`DELETE /api/v1/lists/:list_id`	Delete a list
`POST /api/v1/lists/:list_id/items`	Add an item. Body: `item_id`, `item_type` (`sponsor` \| `podcast` \| `category` \| `contact`). Returns `409` if already in the list
`DELETE /api/v1/lists/:list_id/items/:item_id`	Remove an item

Items are keyed the same way as everywhere in the API: sponsors by domain, podcasts by podcast_id, categories by category_id, and contacts by contact_id.

Example: add a sponsor to a list

curl

curl -X POST https://app.sponsorable.com/api/v1/lists/4645de26-17a1-42a1-8e82-6d2c1475c880/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "item_id=shopify.com" \
  -d "item_type=sponsor"

API Reference

Overview

Base URL

Authentication

Example Request

Credits

Rate Limiting

Errors

Error Response Format

List Sponsors

Query Parameters

Example Request

Response

Response Fields

Get Sponsor

Path Parameters

Example Request

Response

Response Fields

Sponsor Object

Top Podcasts & New Podcasts Arrays

Top Categories Array

Errors

Get Sponsor Contacts

Example Request

Response

Response Fields

Reveal Contact

Example Request

Response

List Podcasts Pro plan

Query Parameters

Response

Get Podcast Pro plan

Response

List Categories

Response

Get Category

Lists

Example: add a sponsor to a list