# Champions

> Job-change tracking for B2B revenue teams. Champions watches the people in your CRM (customers, champions, evaluators) on LinkedIn, detects when they move or get promoted, scores the new company and role against your ICP, and hands you a play with a suggested opener.

- Product: https://getchampions.io
- App: https://app.getchampions.io (invite-only; contact support@getchampions.io)
- API reference (human): https://docs.getchampions.io
- REST base URL: https://api.getchampions.io/v1 (also served at https://app.getchampions.io/api/v1)
- OpenAPI 3.1: https://api.getchampions.io/openapi.json
- MCP server: https://mcp.getchampions.io (Streamable HTTP, OAuth 2.1 or API key) - docs at https://docs.getchampions.io/mcp
- Support: support@getchampions.io

## Authentication

Send a workspace API key (created in the app under Settings → API & integrations) as `Authorization: Bearer chp_live_…` or `X-API-Key`. Scopes: `read` (GET) and `write` (POST/PATCH/PUT/DELETE). OAuth 2.1 with PKCE and dynamic client registration is available for agents: discovery at `https://app.getchampions.io/.well-known/oauth-authorization-server`.

## Concepts

- **Contact**: a person from your CRM. Needs a LinkedIn URL to be tracked. `tracking_status`: needs_linkedin, ready, tracked, not_found, excluded.
- **Profile**: what we found on LinkedIn for a tracked contact. `status`: same_role, promoted, moved, left, unknown, not_found.
- **Change**: a detected event (moved, promoted, title_changed, left, profile_not_found) with from/to company and title. A promotion is a step up in seniority or a new position at the same employer; a step down or a title edited in place is title_changed and creates no play.
- **Play**: the recommended action for a change - direct (account + contact fit), referral (account fit), watch (contact fit), promotion, archive, churn_risk (a contact at a customer account left or moved away; for CS, the opener is an internal note) - with status open → contacted → replied → meeting. A move out of a customer account carries both a sales play and a churn_risk play. `crm_record_id` is set once the play was written back to HubSpot.
- **Settings**: refresh cadence, `track_promotions`, Slack alert routing (`slack_channel_alerts`, `slack_dm_owners`, `alert_play_types`) and HubSpot write-back (`hubspot_writeback_enabled`, `hubspot_writeback_mode` create_new | update_existing, `hubspot_writeback_play_types`).
- **ICP**: account rules (industries, size, HQ, keywords, funding, exclusions) and contact rules (titles, seniority, functions).
- **Run**: a refresh that checks every tracked profile on a cadence (weekly/biweekly/monthly/quarterly) or on demand. One credit per profile checked.
- **Webhook**: HTTPS endpoint receiving `play.created`, `contact.changed`, `run.completed`, `run.paused`; signed with `X-Champions-Signature`.

## REST endpoints

- `GET /v1/me` - Who am I
- `GET /v1/credits` - Credit balance and usage
- `GET /v1/settings` - Get workspace settings
- `PATCH /v1/settings` - Update workspace settings
- `GET /v1/contacts` - List contacts
- `POST /v1/contacts` - Add or update contacts
- `GET /v1/contacts/{id}` - Get a contact
- `PATCH /v1/contacts/{id}` - Fix or exclude a contact
- `DELETE /v1/contacts/{id}` - Delete a contact (GDPR)
- `GET /v1/accounts` - List accounts
- `POST /v1/accounts` - Add or update accounts
- `GET /v1/accounts/{id}` - Get an account
- `GET /v1/changes` - List job changes
- `GET /v1/plays` - List plays
- `GET /v1/plays/{id}` - Get a play
- `PATCH /v1/plays/{id}` - Update play status or notes
- `GET /v1/icp` - Get ICP rules
- `PUT /v1/icp` - Replace ICP rules
- `GET /v1/runs` - List refresh runs
- `POST /v1/runs` - Refresh now
- `GET /v1/runs/estimate` - Estimate a manual refresh
- `GET /v1/runs/{id}` - Get a run
- `POST /v1/runs/{id}/resume` - Resume a paused run
- `POST /v1/runs/{id}/cancel` - Cancel a run
- `GET /v1/webhooks` - List webhook endpoints
- `POST /v1/webhooks` - Create a webhook endpoint
- `DELETE /v1/webhooks/{id}` - Delete a webhook endpoint
- `POST /v1/webhooks/{id}/test` - Send a test delivery
- `GET /v1/webhooks/{id}/deliveries` - List deliveries

Responses are JSON; lists are `{ data, page, page_size, total }`; errors are `{ error: { code, message, details? } }`. Rate limits: 600 read / 120 write per minute per workspace.

## MCP tools

- `get_workspace` - Who you are connected as, credit balance and price per check, refresh schedule and the next scheduled refresh.
- `list_contacts` - The people in the workspace with tracking status and, when tracked, their current company/title and last change. Filter by tracking_status (needs_linkedin, tracked, not_found…), profile status (moved, promoted, left, same_role), segment, owner, account_id, or free-text q.
- `get_contact` - Full detail for one contact: position history, detected changes, ICP fit evaluations, emails and plays.
- `add_contacts` (write) - Upsert up to 1,000 contacts (and optionally the accounts they belong to). Contacts with a LinkedIn URL start tracking right away; the rest wait in Needs LinkedIn. Dedupes on crm_id, then LinkedIn URL, then email, then name+company.
- `update_contact` (write) - Give a contact its LinkedIn URL (resolves Needs LinkedIn / Not found and starts tracking) or exclude it from tracking.
- `list_accounts` - Companies in the CRM with contact counts (total, tracked, moved).
- `get_account` - One account with all its contacts.
- `list_changes` - Detected moves, promotions, title changes (lateral/demotion, no play), departures and unreachable profiles, newest first. Use since (ISO timestamp) for 'what changed this week'.
- `list_plays` - Plays are the recommended action for a change: direct (account and contact fit), referral (account fit only), watch (contact fit only), promotion, archive, churn_risk (a contact at a customer account left or moved away — for CS). Open plays first. Each play carries the person's new role, the old relationship, the best email and a suggested opener.
- `get_play` - One play by id.
- `update_play` (write) - Move a play through open → contacted → replied → meeting, mark it not_relevant, or attach notes.
- `get_icp` - Active account and contact fit rules. Account rules: industries, employee range, HQ countries/regions, keywords, funding stages, exclusions. Contact rules: title include/exclude, seniority, functions.
- `update_icp` (write) - Replace the account and/or contact rules. Read get_icp first and send the full rule object back with your edits; each changed set becomes a new version.
- `list_runs` - Recent refresh runs with status and totals (moved, promoted, credits charged).
- `get_run` - Status and live totals of one run; poll it while a run is in progress.
- `estimate_refresh` - How many profiles a 'refresh now' would check and what it costs in credits/cents. Profiles checked in the last 24h are skipped. Always call this and confirm with the user before start_refresh.
- `start_refresh` (write) - Queue a manual refresh of every tracked profile not checked in the last 24 hours. Spends one credit per profile - confirm with the user first (see estimate_refresh). Returns the existing run if one is already active.
- `resume_run` (write) - Resume a run paused for lack of credits after topping up.
- `cancel_run` (write) - Cancel a queued, running or paused run.
- `update_settings` (write) - Change the workspace name or refresh cadence (weekly, biweekly, monthly, quarterly), day and timezone.
- `delete_contact` (write) - Permanently delete a contact and, if nobody else references the person, everything held about them. Irreversible - confirm with the user.