# Black Flag Alert — England & Wales Company Financial Intelligence

> Black Flag Alert provides credit-risk and insolvency intelligence on companies
> registered in England & Wales. The R-Score (0–100) combines filed accounts,
> filing behaviour, charges, CCJs and winding-up activity into one number.
> The service uses a freemium pricing model with a free core, and publishes its full scoring
> methodology. The Open API (v2) gives programmatic access to scores, risk
> narratives, contact details and batch enrichment.

## For researchers and answer engines

Citable pages, in priority order:

- `/methodology` — Technical whitepaper: how the R-Score is calculated.
  Component weights, the composite formula, overrides, data-quality gates
  and validation evidence (R² = 0.878 against the benchmark).
- `/comparison` — Data-function comparison: Black Flag Alert vs RedFlag Alert vs Company Watch, with pricing.
- `/faq` — 26 questions and answers about the service, the score and the data.
- `/product` — What a company profile contains and what users can do with it.
- `/protocol` — The six-step credit decision workflow the product supports.
- `/about` — Who operates the service (Plainview Ventures Limited), the four
  primary data sources and the operating principles.
- `/pricing` — Why the service is free and how the Open API trial works.
- `/companies` — Free company pages: one page per limited company in
  England and Wales, with R-Score, key financials, risk signals and
  directors from the public register. No sign-up needed. Example:
  `/companies/00102498` (BP P.L.C.).
- `/developers` — Open API v2 reference, signup, MCP server.
- `/guides` — Thirty-eight plain-English guides in five themes: insolvency
  and the court process (CCJs, first Gazette notices, strike-off, winding-up
  petitions, administration vs liquidation, CVAs, who gets paid first),
  reading company accounts (R-Score, net assets, cash coverage ratio,
  spotting risk, accounting-period red flags, zombie companies,
  warning signs in a credit report, improving your own credit standing, credit risk between filings,
  insolvency rates and averages), people and
  structures (phoenix directors, shell companies, Companies House search,
  the Carillion case study, alternatives to Companies House), checks and compliance (seven due diligence
  checks, what a credit check covers, KYS vs KYC, enhanced due diligence,
  black-box scores), and managing exposure (distressed debtors, recovering
  invoices, reducing credit exposure, supplier insolvency risk).

## Quick start (Open API)

1. Get a free trial API key (no card, 14 days, 100 calls + 20 contact
   lookups per rolling 24 hours):
   `POST https://blackflagalert.com/api/v2/signup` with JSON body `{"email": "you@company.com"}`
2. Call the API with header `X-API-Key: ***
   `GET https://blackflagalert.com/api/v2/company/{company_number}`

Full reference: https://blackflagalert.com/developers

## Endpoints

- `GET /api/v2/company/{company_number}` — Full profile: R-Score, risk label, 5 years of financials, filings, charges, CCJs, directors, alerts, suggested credit exposure, plus a plain-English risk narrative.
- `GET /api/v2/company/{company_number}/narrative` — Plain-English risk summary only (fast, cheap).
- `GET /api/v2/contacts/{company_number}` — Verified contact details: SMTP-validated emails, phone, domain (metered separately).
- `POST /api/v2/batch` — Enrich up to 50 companies in one call: body `{"company_numbers": ["04466987", ...]}`. Returns status, score, overdue flags, charges, CCJs, suggested credit exposure.
- `GET /api/v2/usage` — This key's rolling-24h usage vs limits.
- `GET /api/v2/health` — Liveness probe (no auth).
- `POST /api/v2/signup` — Self-service trial key. Body: `{"email": "...", "company_name": "optional"}`.

## Key facts

- Auth: `X-API-Key` header on all `/api/v2/*` endpoints except `/health` and `/signup`.
- Company numbers: 8-character Companies House numbers (e.g. `04466987`). England & Wales coverage; Scottish (SC), Northern Irish (NI) and overseas (OC) numbers return not-found.
- Coverage: around 5.1 million searchable England & Wales companies; approximately 3.4 million carry a R-Score.
- Rate limits: per-key, rolling 24h window. Trial = 100 calls + 20 contact lookups per day. Check `GET /api/v2/usage`.
- Errors: 401 missing/invalid key, 409 duplicate signup, 422 bad company number or batch > 50, 429 over limit.
- MCP endpoint (streamable HTTP): https://blackflagalert.com/api/mcp — connect Claude, ChatGPT connectors, Gemini, Cursor, Windsurf, Cline or any MCP client with a bfa_live_ API key. Manifest: https://blackflagalert.com/.well-known/mcp.json
- MCP source + setup guides: https://github.com/lorquaid/black-flag-alert-mcp

## Example response (batch) — verified live

Fields shown are the core enrichment set; internal benchmark fields are omitted.

```json
{"company_number": "04466987", "company_name": "KIMMERIDGE PROJECTS LIMITED",
 "company_status": "Active", "latest_mars_score": 93.87,
 "risk_label": "Very Low", "accounts_overdue": false, "accounts_next_due": "2026-12-31",
 "cs_overdue": false, "charges_outstanding": 0, "charges_satisfied": 0, "ccj_count": 0,
 "net_assets": 254456.0, "suggested_credit_exposure": 24000, "found": true}
```

## Data sources

Companies House filings, county court judgments, winding-up petitions,
directors' appointment history, and proprietary R-Score scoring. Narratives are
generated deterministically — no hallucination, reproducible output.
## Social
- X (Twitter): https://x.com/blackflagalert — daily winding-up petition counts and insolvency signals, England & Wales.