Skip to main content

Core concepts

AdBridge connects podcasts with advertisers. This page explains the entities you'll work with, how they relate, and the two workflows that tie them together. Once these click, the API Reference — which is organized in the same order — will read naturally.

The cast​

EntityWhat it is
NetworkAn organization. It owns podcasts, campaigns, members, and integrations. Almost everything is scoped to a network.
PodcastA show owned by a network. It can opt in to advertising and has one or more host voices.
VoiceA host's cloned voice belonging to a podcast, used to read ads aloud.
AdvertiserA brand that runs campaigns. Defined platform-wide and referenced by a network's campaigns.
CampaignAn advertising campaign within a network, run on behalf of an advertiser.
OfferA single campaign matched to a podcast — the unit a podcaster accepts or rejects.
CreativeThe finished host-voiced ad generated for a podcast after an offer is accepted.

How they relate​

Network
├── Members            (people / service accounts with a role)
├── Podcasts
│   └── Voices         (host voices used to read ads)
├── Advertisers        (referenced by the network's campaigns)
├── Campaigns
│   └── Offers         (a campaign matched to one podcast)
│       └── Creative   (host-voiced ad, produced when the offer is accepted)
└── Webhooks           (event notifications)
  • A podcast belongs to a network and owns its voices.
  • A campaign belongs to a network and points at an advertiser.
  • An offer ties one campaign to one podcast. Accepting it produces a creative that uses one of the podcast's voices.

Workflow 1 — Onboard a podcast (opt-in)​

Before a podcast can receive offers, it opts in. This spans an admin (API key) step and a recipient (magic-link) step:

  1. Admin sends an opt-in invitation — POST /v1/networks/{networkId}/podcasts/{podcastId}/opt-in-invitations. AdBridge emails the podcast contact a magic link.
  2. Recipient opens the link and completes opt-in via the public, no-API-key Opt-in flow (and optionally creates a host voice via Opt-in voice). See Public token flows.
  3. The podcast is now opted in and can be matched to campaigns. An optin.completed webhook fires.

Workflow 2 — Run a campaign​

  1. Create the advertiser (if it doesn't exist yet) — POST /v1/networks/{networkId}/advertisers.
  2. Create a campaign for that advertiser — POST /v1/networks/{networkId}/campaigns.
  3. Send an offer to a podcast — POST /v1/networks/{networkId}/campaigns/{campaignId}/offers. AdBridge emails the podcast owner a magic link to review it.
  4. Recipient accepts via the public Campaign offer flow (or rejects). On accept, AdBridge starts generating the host-voiced creative.
  5. Creative generation is asynchronous. Poll the creative until its status is ready (or failed), or subscribe to the creative.ready / creative.failed webhooks to be notified.
advertiser → campaign → offer ──accept──▶ creative (pending → ready)
                          │
                          └─ podcast owner reviews via magic link

Access model​

Who can do what is governed by API keys scoped to networks at a role:

  • A key grants read_only or administrator on each network it's scoped to.
  • Members are the people (and service accounts) in a network; their role bounds what their keys can do.
  • Service accounts are non-human members for integrations, so credentials don't ride on a person.

See Authentication for the details, and mint/manage keys under API keys.

Two kinds of caller​

The API has two distinct audiences — keep them straight:

Your integrationThe recipient
Authenticates withAn API key (Authorization: Bearer)A magic-link token in the URL
CallsEverything under /v1 except /v1/public/**Only /v1/public/**
ExampleCreate a campaign, send an offerAccept an offer, complete opt-in

The recipient endpoints exist so you can build the pages a podcaster sees — see Public token flows.

What's next​