# Compabase

> Intelligent Polish company data — search, profiles, export, REST API, MCP, and AI assistant.

Compabase is a B2B analytics platform aggregating, normalizing, and serving structured business information from public Polish registries (KRS, CEIDG, e-Financial Statements, VAT whitelist, GPW, SUDOP, BZP, TED, URE, BDO, CRBR, KRZ, MSiG, FE, FTS).

- Website: https://compabase.com
- API docs (Redoc): https://compabase.com/docs/
- MCP docs (Redoc): https://compabase.com/docs/mcp/
- OpenAPI spec: https://compabase.com/openapi/v1.yaml
- MCP OpenAPI spec: https://compabase.com/openapi/mcp.yaml
- Full LLM documentation: https://compabase.com/llms-full.txt
- Pricing: https://compabase.com/pricing

## What Compabase Does

Compabase lets users verify contractors, assess risk, and find reliable business partners based on current registry and financial data of Polish entities. It is informational/analytical only (not legal or financial advice).

Key differentiator: ultra-detailed, structured data from financial statements (full balance sheet and income statement positions parsed from e-SF/ESEF XML files), with computed ratios, narrative insights, and Sankey flow charts.

## Access Modes

1. **Web browsing** — search and browse company profiles at compabase.com
2. **REST API v1** — versioned JSON API with API key authentication
3. **MCP server** — Model Context Protocol for AI agents (Streamable HTTP, JSON-RPC 2.0)
4. **AI assistant ("Ask AI")** — chat answering questions about company data
5. **Data export** — CSV/XLS structured datasets (paid plans)

## Data Sources

| Source | Type | Coverage |
|--------|------|----------|
| KRS | Public registry | Companies, associations; registry data, people, structure |
| CEIDG | Public registry | Sole proprietorships (JDG) |
| e-Financial Statements (MF) | Public repository | Full balance sheet and income statement from XML e-SF/ESEF |
| VAT Whitelist (MF) | Public registry | VAT status, business bank accounts |
| GPW / NewConnect / GlobalConnect | Delayed quotes (~15 min) | Ticker, ISIN, price, market cap, P/E, dividend |
| SUDOP | Public registry | Public aid / de minimis cases |
| BZP | Public registry | Polish public procurement contracts |
| TED | Public registry | EU-threshold procurement |
| URE | Public registry | Energy concessions |
| BDO | Public registry | Waste and packaging register |
| CRBR | Public registry | Beneficial owners (KRS companies) |
| KRZ | Public registry | Insolvency / restructuring proceedings |
| MSiG | Public registry | Court and Commercial Gazette notices |
| FE | Public registry | European Funds (cohesion) projects |
| FTS | Public registry | EU Commission Financial Transparency System grants |

## Plans and Limits

| Plan | Price/month (PLN) | Price/month (USD) | Price/month (EUR) | Export | API requests | AI analyses | MCP queries | Watchlist | BYOK |
|------|-------------------|-------------------|-------------------|--------|-------------|-------------|-------------|-----------|------|
| Free | 0 PLN | $0 | €0 | 50 | 100 | 3 | 10 | 10 | no |
| Pro | 99 PLN | $29 | €25 | 1,000 | 5,000 | 20 | 50 | unlimited | yes |
| Scale | 999 PLN | $279 | €239 | 20,000 | 100,000 | 300 | 1,000 | unlimited | yes |
| Enterprise | custom | custom | custom | unlimited | unlimited | unlimited | unlimited | unlimited | yes |

## REST API v1 — Quick Reference

Base URL: `https://compabase.com/api/v1/`
Authentication: `X-API-Key: <key>` or `Authorization: Bearer <key>`
Keys: self-service at https://compabase.com/integrations

### Endpoints

| Method & Path | Description |
|---------------|-------------|
| `GET /health` | API status (no key) |
| `GET /companies` | Search and list companies (filters, pagination) |
| `GET /companies/count` | Count companies matching filters |
| `GET /companies/export` | Bulk search export (up to 500 rows/page) |
| `GET /companies/krs/{krs}` | Full company profile by KRS |
| `GET /companies/krs/{krs}/status` | Legal status |
| `GET /companies/krs/{krs}/financial-statements` | Financial metrics by year |
| `GET /companies/krs/{krs}/financial-documents` | Document inventory metadata |
| `GET /companies/krs/{krs}/statistics` | Peer benchmarks and rankings |
| `GET /companies/krs/{krs}/structure-people` | Ownership and management |
| `GET /companies/krs/{krs}/connections` | Related companies/people graph |
| `GET /companies/krs/{krs}/news` | News and UGC |
| `GET /companies/krs/{krs}/gpw` | GPW stock exchange listing |
| `GET /ceidg/nip/{nip}` | CEIDG sole proprietor profile by NIP |
| `GET /persons/search` | Search persons by name |
| `GET /persons/{personId}/connections` | Person's company connections |
| `GET /watchlist` | List watchlist |
| `POST /watchlist/krs/{krs}` | Add to watchlist |
| `DELETE /watchlist/krs/{krs}` | Remove from watchlist |
| `GET /usage` | Monthly quota usage |

## MCP Server — Quick Reference

Endpoint: `https://compabase.com/api/mcp`
Protocol: MCP Streamable HTTP (JSON-RPC 2.0)
Authentication: `Authorization: Bearer mcpk_…`
Keys: self-service at https://compabase.com/integrations?tab=mcp

### Client Configuration (Cursor / VS Code / Windsurf)

```json
{
  "mcpServers": {
    "compabase": {
      "url": "https://compabase.com/api/mcp",
      "headers": { "Authorization": "Bearer mcpk_YOUR_KEY_HERE" }
    }
  }
}
```

### MCP Tools

**Onboarding (no key required):**
- `request_signup` — start account setup, sends magic link email
- `check_signup` — poll signup status, receive MCP key
- `list_plans` — list billing plans and limits

**Data tools (consume mcp_queries quota):**
- `search_companies` — KRS companies (default `fields=summary`; `contacts_only` = name/NIP/city/email/phone/www; `county` = powiat; full CEIDG/JDG is in Compabase, listing is RODO-gated; sparse JDG-heavy PKDs include a `hint`)
- `count_companies` — count matching companies
- `get_company` — registry profile, headline financials, and contacts (KRS; or JDG with a public email)
- `get_financials` — full financial statement metrics per period
- `get_company_people` — board members, shareholders, proxies
- `get_company_rankings` — revenue rank by industry/region/country
- `get_financial_stats` — aggregate sector/region statistics (median, percentiles)
- `get_company_gpw` — GPW stock exchange listing and quotes
- `get_company_sudop` — public aid / de minimis cases
- `get_company_bzp` — Polish public procurement
- `get_company_ted` — EU TED procurement
- `get_company_ure` — energy concessions
- `get_company_bdo` — waste/packaging register
- `get_company_msig` — Court and Commercial Gazette notices
- `get_company_krz` — insolvency/restructuring proceedings
- `get_company_beneficiaries` — CRBR beneficial owners
- `get_company_fe` — European Funds projects
- `get_company_fts` — EU Commission grants (FTS)
- `execute_sql` — read-only SQL SELECT on whitelisted views

**Account tools (no quota cost):**
- `get_usage` — billing period usage and remaining quota
- `get_plan` — active plan details
- `list_watchlist` / `add_to_watchlist` / `remove_from_watchlist` / `batch_add_to_watchlist`
- `list_api_keys` / `create_api_key` / `delete_api_key`
- `list_mcp_keys` / `create_mcp_key` / `delete_mcp_key`
- `export_companies` — bulk CSV/XLSX/JSON (default `fields=contacts_only`; `county` = powiat; consumes export quota)
- `upgrade_plan` — get Stripe checkout URL
- `set_webhook_url` — configure watchlist webhooks
- `get_byok_keys` / `set_byok_key` / `delete_byok_key` — BYOK AI provider keys
- `set_notification_preferences` — email notification settings

## Financial Data Detail

Parsed from e-SF XML files (all entity types: standard/large, small, micro, NGO):
- **Balance sheet:** fixed/current assets breakdown, cash, receivables, inventories, equity, liabilities, provisions, total assets
- **Income statement:** revenue (products, goods/materials), cost breakdown (wages, amortization, external services), operating profit, EBIT, gross/net profit, income tax
- **Ratios:** ROA, ROE, margins, liquidity, EBITDA; currencies PLN/USD/EUR
- **Validation:** arithmetic consistency checks before storage

## Error Model

```json
{
  "statusCode": 400,
  "statusMessage": "...",
  "message": "...",
  "data": {
    "error": {
      "code": "INVALID_KRS",
      "message": "After normalization, KRS must contain exactly 10 digits.",
      "details": { "parameter": "krs" }
    }
  }
}
```

Error codes: `INVALID_KRS`, `INVALID_NIP`, `INVALID_CURSOR`, `INVALID_RANGE`, `INVALID_PARAMETER`, `CONFLICTING_PARAMETERS`, `INVALID_BOOLEAN`, `INVALID_KEYWORDS`, `INVALID_API_KEY`, `UNAUTHORIZED`, `NOT_FOUND`, `QUOTA_EXCEEDED`.

## GDPR / Data Protection

Administrator: Content Writer sp. z o.o. (NIP 7792567297, KRS 0001088645).
GDPR channel: compliance@compabase.com

- Personal data published only from KRS/CEIDG (not enriched from external sources)
- PESEL and full birth date never exposed (approximate age via birth_year only)
- AI assistant does not train models on platform data
- Contact email masked for unauthenticated users

## Optional Links

- Full LLM documentation (all API/MCP details): https://compabase.com/llms-full.txt
- OpenAPI v1 YAML: https://compabase.com/openapi/v1.yaml
- MCP OpenAPI YAML: https://compabase.com/openapi/mcp.yaml
- Interactive API docs: https://compabase.com/docs/
- Interactive MCP docs: https://compabase.com/docs/mcp/