my-people-api

---
name: my-people-api
version: 1.0.0
description: >
  Contact database backed by the Goldfox crawl. Filter people by Goldfox confidence tier, seniority, email type, country, link confidence, plus rich behavioral company signals (has_c_level, has_careers_page, has_decision_maker, etc.). The targeting layer for outbound campaigns.
triggers: [people, contacts, leads, prospects, search, filter, goldfox, decision-makers, c-level, b2b targeting, corporate email]
checksum: sha256-pending
---

# MyPeopleAPI

A queryable contact database for B2B targeting, sourced from the **Goldfox** crawl. The data model is signal-rich: every row carries a Goldfox confidence tier, a per-link confidence score, an email type classification, and the embedded company's behavioral signals (has_c_level, has_careers_page, etc.). Filter on those signals to get high-precision target lists.

## Capabilities
<!-- llm:start -->
The database returns people with their embedded company. Use when:

- Building an outbound list with strong precision controls (e.g. only corporate-email c_levels in DE)
- Filtering for buying signals (companies with careers/investors/shop pages, decision-makers present)
- Combining with `my-audience-api` to save a filter snapshot for reuse across campaigns

Filter contract — shared with `my-company-api` and the `filter` field of `my-audience-api`. OR within an array; AND across fields. **Empty filter = all rows with default confidence=high (Goldfox's curated tier).**

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

Allowed values:
- **confidence**: `high` (default — 96.4% of dataset, no UGC) / `low` (UGC source — spot-check) / `very_low` (UGC + freemail mismatch — usually drop)
- **seniority**: `c_level`, `vp_director`, `manager`, `senior_ic`, `ic`
- **email_type**: `corporate`, `freemail`, `role_based`, `other_corporate`
- **tld_class**: `cctld`, `generic`, `vanity`, `low_trust`, `other`
- **country**: ISO 3166-1 alpha-2 (US, DE, GB, …) — consensus across TLD + address + phone
- **keyword**: case-insensitive substring on the row's domain (NOT name or title)
- **link_confidence**: 0–1 per person; 1.0 = email-domain match (definitive), 0.5 = strong, lower = weak
<!-- llm:end -->

## Commands
<!-- generated:start -->
| Command | What it does |
|---|---|
| `myapi people search [--confidence <csv>] [--country <csv>] [--seniority <csv>] [--email-type <csv>] [--tld-class <csv>] [--has-c-level] [--has-decision-maker] [--has-careers-page] [--has-investors-page] [--has-shop-page] [--is-registered-entity] [--country-consistent] [--keyword <text>] [--min-headcount N] [--min-source-count N] [--min-link-confidence 0..1] [--limit N] [--offset N]` | Filter people; returns id/name/email/domain/country/link_conf table |
| `myapi people get <person_id>` | Get a single person with embedded company |
<!-- generated:end -->

CSV-flag values use OR within (e.g. `--seniority c_level,vp_director` is `seniority IN (c_level, vp_director)`). Boolean flags are presence-only (`--has-c-level` enables it; omit to leave unfiltered).

## Examples
<!-- llm:start -->
```bash
# 1. Decision-makers in DE/FR/GB with corporate emails
myapi people search \
  --seniority c_level,vp_director \
  --country DE,FR,GB \
  --email-type corporate \
  --limit 20

# 2. High-precision filter: definitive link + registered entity + careers signal
myapi people search \
  --min-link-confidence 0.9 \
  --is-registered-entity \
  --has-careers-page \
  --country US

# 3. Single person with full company context
myapi people get p_MTdlc2llY2xlLmZy.0
```

### End-to-end recipe — outbound campaign target list

```bash
# Build the target audience (saved filter)
AID=$(myapi audience create "EU decision makers w/ careers signal" \
  --source people \
  --filter '{"seniority":["c_level","vp_director"],"country":["DE","FR","GB"],"email_type":["corporate"],"has_careers_page":true}' \
  --json | jq -r .id)

# Pull members for inspection
myapi audience members $AID --limit 100 --json > targets.json
```
<!-- llm:end -->

## Notes

- The dataset is the Goldfox crawl — multi-million-row corporate contact data with provenance signals. Filter quality matters: defaults to `confidence=high` gives 96.4% of rows by count, but it's the curated tier; widening with `confidence=low` brings UGC rows that need spot-checking.
- `seniority`, `email_type`, and `min_link_confidence` are people-only — silently ignored on `my-company-api` and on audiences with `--source company`.
- `keyword` matches the row's **domain**, not name/title. Use `--keyword acme` to find people whose domain contains "acme".
- For a persistent target list, use `my-audience-api` (snapshot the filter; re-evaluate on `audience refresh`).

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