my-audience-api

---
name: my-audience-api
version: 1.0.0
description: >
  Saved audiences = named Goldfox-filter snapshots over the people or company database. Build a target list once, name it, reuse it across campaigns, refresh to re-evaluate against current data. The persistence layer on top of my-people-api + my-company-api.
triggers: [audience, segment, target list, saved filter, goldfox, lead list, abm list, refresh, members, prospect database]
checksum: sha256-pending
---

# MyAudienceAPI

A saved audience is a **named filter snapshot** over the Goldfox people or company database. Instead of repeating the same filter every time you run a campaign, save it once, reference the audience by id, and call `refresh` to re-evaluate against current data when the underlying dataset grows.

## Capabilities
<!-- llm:start -->
Use when:

- You'll target the same kind of list across multiple campaigns
- You want a stable id to feed into email campaigns, workflows, or external tools
- You need to know how many candidates match a filter without paging the whole result
- You want to refresh a list as new rows are added to the Goldfox crawl

Each audience has:
- `name` and optional `description`
- `source` — `"people"` or `"company"` (which database to filter against)
- `filter` — the canonical Goldfox filter (same shape as `my-people-api` / `my-company-api`)
- `member_count` — computed when filter is created or refreshed
- An `id` for retrieving members, refreshing, deleting

**Filter contract** (full Goldfox shape):

```json
{
  "confidence":           ["high"],
  "country":              ["US", "DE"],
  "country_consistent":   true,
  "seniority":            ["c_level", "vp_director"],   // people-source only
  "email_type":           ["corporate"],                // people-source only
  "tld_class":            ["cctld"],
  "has_c_level":          true,
  "has_decision_maker":   true,
  "has_careers_page":     true,
  "has_investors_page":   false,
  "has_shop_page":        false,
  "is_registered_entity": true,
  "min_headcount":        5,
  "min_source_count":     3,
  "min_link_confidence":  0.8,                          // people-source only
  "keyword":              "platform",
  "limit":                100,
  "offset":               0
}
```

OR within an array; AND across fields. Empty filter = all rows with `confidence=high` (Goldfox's curated default tier).

Allowed values:
- **confidence**: `high` (default) / `low` / `very_low`
- **seniority** (people only): `c_level`, `vp_director`, `manager`, `senior_ic`, `ic`
- **email_type** (people only): `corporate`, `freemail`, `role_based`, `other_corporate`
- **tld_class**: `cctld`, `generic`, `vanity`, `low_trust`, `other`
- **country**: ISO 3166-1 alpha-2

**Member fetch:** the response shape is `{ total, limit, offset, has_more, people?: […], companies?: […] }` — only one of `people` / `companies` is populated based on the audience's source. Use `--offset` to paginate.

**Refresh delta:** `audience refresh` returns `{ total, previous, delta, refreshed_at }` — detect newly-matched rows.
<!-- llm:end -->

## Commands
<!-- generated:start -->
| Command | What it does |
|---|---|
| `myapi audience create <name> --source <people\|company> --filter '<json>' [--description <text>]` | Save a Goldfox filter as a named audience; returns id + initial member_count |
| `myapi audience list` | List all audiences in the org |
| `myapi audience get <id>` | Single audience (name, filter, member_count, timestamps) |
| `myapi audience update <id> [--name <x>] [--description <y>] [--filter '<json>']` | Patch name/description/filter; member_count re-evaluates if filter changes |
| `myapi audience delete <id>` | Remove an audience |
| `myapi audience members <id> [--limit N] [--offset N]` | Paged member snapshot (people or companies depending on source) |
| `myapi audience refresh <id>` | Re-evaluate filter against current data; returns delta vs previous count |
<!-- generated:end -->

## Examples
<!-- llm:start -->
```bash
# 1. Create the audience
AID=$(myapi audience create "EU decision makers w/ corporate emails" \
  --source people \
  --filter '{"seniority":["c_level","vp_director"],"country":["DE","FR","GB"],"email_type":["corporate"]}' \
  --json | jq -r .id)

# 2. Inspect members
myapi audience members $AID --limit 20

# 3. Refresh after new Goldfox data lands
myapi audience refresh $AID
# → Refreshed. 1247 → 1289 (+42)

# 4. Update filter without losing the id
myapi audience update $AID \
  --filter '{"seniority":["c_level","vp_director"],"country":["DE","FR","GB","NL"],"email_type":["corporate"]}'

# 5. Delete when done
myapi audience delete $AID
```

### End-to-end recipe — outbound campaign driven by an audience

```bash
# Build with quality controls — definitive links + registered companies + careers signal
AID=$(myapi audience create "EU growth-stage decision makers" \
  --source people \
  --filter '{"seniority":["c_level","vp_director"],"country":["DE","FR","GB"],"email_type":["corporate"],"min_link_confidence":0.9,"has_careers_page":true,"is_registered_entity":true}' \
  --json | jq -r .id)

# Pull all members as JSON
myapi audience members $AID --limit 100 --json > targets.json

# (later) Re-check before next batch
myapi audience refresh $AID
```

### Company-source audience (ABM)

```bash
myapi audience create "EU growth-stage SaaS accounts" \
  --source company \
  --filter '{"country":["DE","FR","GB","NL"],"has_careers_page":true,"has_decision_maker":true,"is_registered_entity":true,"min_source_count":3}'
```
<!-- llm:end -->

## Notes

- The underlying dataset is the **Goldfox crawl** — multi-million-row corporate data with provenance signals. Defaults to `confidence=high` which is the curated tier.
- `audience refresh` is cheap and idempotent; call it before any campaign run that depends on a current list.
- `update --filter` REPLACES the whole filter (not merged). To shift one field, fetch the audience, merge in code, then update.
- Audiences are per-org. Two orgs can have audiences with the same name; ids are globally unique.
- Look before you delete: confirm the target with `myapi audience get <id>`, pass `--org` explicitly; delete verbs require `--yes` in non-interactive runs.

Run `myapi audience --help` for full flag reference.