Team workspaces — shared pipeline, scoped data and pooled credits

What it is

Create a workspace with a name and slug (POST /api/workspaces), invite teammates by email with a role, and everything collaborative becomes shared: the KOL database view (team scope), lists with their triage states, CRM conversations and tasks, the activity feed, and cached AI artifacts like activity summaries. Personal accounts keep working unchanged — a workspace is opt-in structure on top.

Data scope: personal / team / both

Every KOL query accepts a scope parameter. personal = only creators you discovered; team = creators discovered by anyone in your active workspace; both = the union (default). Isolation is enforced server-side on every request — KOLens never returns a creator that nobody in your workspace surfaced. This is what makes one workspace per client viable for agencies: client A's research can't leak into client B's view.

Brand profile

Workspace settings (GET/PUT /api/workspaces/{slug}/settings) hold the brand profile: what you sell, who you target, budget posture and brand voice. Two systems read it: AI outreach drafting (emails pitch your actual product in your actual tone) and the recommendation component of list fit scores (creators are scored against your brand, not a generic ideal). Fill it in once during onboarding — it's the single highest-leverage configuration in the product.

Pooled credits & billing

• Admins grant credits to a shared pool (POST /api/workspaces/{slug}/billing/grant-credits); member charges drain the pool first, then fall back to personal balances.
• Billing summary (GET /api/workspaces/{slug}/billing/summary) shows total credits, spend and top spenders; history is the full ledger; the Stripe portal manages payment methods.
• The result: one invoice, one budget, per-member visibility — finance gets the rollup, researchers never hit a personal paywall mid-task.

How to set up a team

1. Create the workspace and fill in the brand profile before inviting anyone — every later AI artifact benefits.
2. Invite members by email with a role (POST /api/workspaces/{slug}/invitations); they accept and land in the shared view.
3. Fund the credit pool to the size of the month's research plan (e.g. 200 credits ≈ 2,000 scraped results).
4. Split roles by workflow: researchers run discovery and triage lists; account managers own CRM stages; admins watch billing.

Typical scenarios

• Agency: one workspace per client, hard data isolation between them, one Stripe invoice each — and the client can be invited read-along late in the campaign.
• Cross-border team: research in Shenzhen, outreach in the US timezone — same lists, same pipeline, no spreadsheet emailing.
• Solo-to-team growth: start personal, create a workspace when the first hire arrives; your existing data joins via scope=both.