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

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):

{
  "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.

Commands

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

Examples

# 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

# 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)

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}'

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.