Metadata-Version: 2.4
Name: prometiam-risk-api
Version: 0.1.0
Summary: Official Python client for the Prometiam Risk Intelligence API: EU company registry data (ES, FR, GB, IE, PL, NO, FI, SE, HR, BE, DK), corporate insolvency across twelve markets, sanctions screening, VAT and LEI lookups.
Author-email: Prometiam <support@prometiam.com>
License: MIT
Project-URL: Homepage, https://www.prometiam.com/risk-api/docs
Project-URL: Documentation, https://www.prometiam.com/risk-api/docs
Keywords: prometiam,kyb,company-registry,sanctions-screening,insolvency,borme,bodacc,companies-house
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25
Dynamic: license-file

# prometiam-risk-api (Python)

Official Python client for the [Prometiam Risk Intelligence API](https://www.prometiam.com/risk-api/docs): company registry data for Spain, France, the UK, Ireland, Poland, Norway, Finland, Sweden, Croatia, Belgium and Denmark, corporate insolvency notices across twelve markets, sanctions screening, VAT and LEI lookups.

```bash
pip install prometiam-risk-api
```

## Quick start

```python
import os
from prometiam_risk_api import Client

api = Client(api_key=os.environ["PROMETIAM_API_KEY"])

page = api.companies_search(name="Inditex", country="ES")   # fuzzy, best match first (match_score 0-100)
first = page["data"][0]
print(first["company_name"], first["company_number"])

detail = api.company(first["id"], include="risk_flags,insolvency")
```

Every method returns the API envelope `{"data": ..., "pagination": ..., "meta": ...}` exactly as documented.

## Batch calls

One HTTP call for a whole list. Every item counts as one request against your plan limits; a batch that does not fit raises `RateLimitError` whose `max_items_now` says how many items would fit.

```python
lookup = api.companies_lookup([
    {"country": "ES", "company_number": "A46103834"},
    {"country": "FR", "siren": "552032534"},
    {"country": "ES", "name": "Inditex"},          # best fuzzy match, with match_score
])
for r in lookup["data"]:
    print(r["status"], (r["company"] or {}).get("company_name"))

screen = api.sanctions_screen_batch(["Vladimir Putin", "Acme Trading Ltd"], group="entity")
flagged = [r for r in screen["data"] if r["status"] == "match"]

distress = api.insolvency_check([
    {"country": "FR", "company_number": "917499519"},
    {"country": "DE", "name": "Wirecard"},
])
```

## Pagination

```python
for page in api.paginate("/people/search", {"name": "garcia", "country": "ES", "limit": 50}):
    for person in page:
        print(person["full_name"])
```

## Errors

| Error | When |
|---|---|
| `AuthError` | 401, or 403 for a country the key cannot access |
| `UpgradeRequiredError` | 403 `upgrade_required`: scope not in your plan or the free trial allowance is used up. Carries `included_in`, `price`, `upgrade_url`, `trial_allowance` |
| `RateLimitError` | 429, retried automatically up to `max_retries` (default 2) honouring `Retry-After`; carries `retry_after` and `max_items_now` |
| `ValidationError` | 400 |
| `NotFoundError` | 404 |
| `PrometiamError` | anything else; `status`, `code`, `body` on every error |

## Options

```python
Client(api_key, base_url="https://api.prometiam.com/functions/v1/risk-api", timeout=30.0, max_retries=2, transport=None)
```

Use `with Client(...) as api:` to close the connection pool, and `api.request("GET", "/coverage")` for anything not wrapped.

## Rate limits

Per-key limits by plan (requests/minute, requests/day, requests/month):

| Plan | Price | RPM | Daily | Monthly |
|---|---|---|---|---|
| Free (14-day trial) | €0 | 10 | 200 | 1,000 |
| Starter | €9.99/mo | 60 | 2,000 | 10,000 |
| Professional | €29.99/mo | 300 | 20,000 | 100,000 |
| Scale | €99.99/mo | 600 | 200,000 | 1,000,000 |
| Enterprise | Custom | Custom | Custom | Custom |

`api.account()` returns your key's current limits and usage (`rate_limit.rpm_remaining`, `daily_remaining`, `monthly_remaining`). A 429 raises `RateLimitError`, retried automatically up to `max_retries` honouring `Retry-After`. Batch calls (`companies_lookup`, `sanctions_screen_batch`, `insolvency_check`) count every item in the list as one request against these limits; a batch that would not fit in the remaining quota raises `RateLimitError` up front (`code == "batch_exceeds_quota"`, `max_items_now` set).

## Scope limits

The API's coverage has real edges — every method above reflects them, not a marketing claim:

- **Company registry (`companies_search`, `company`, `people_search`, `events_*`, `directors_network`):** Spain, France, the UK, Ireland, Poland, Norway, Finland, Sweden, Croatia, Belgium, Denmark. Ireland and Poland are company-level today (no officers yet). Finland, Sweden, Croatia, Belgium and Denmark are company records only, with register-change events (name, status, legal form and registered address; share capital for Croatia; dated when the change first appears in the register data, not gazette notices, none before 2026-09-30) and monitoring, but no officers and no registry-compliance signal. Corporate insolvency notices are linked by business ID (Finland), organisationsnummer (Sweden), MBS (Croatia) and CVR number (Denmark); Belgium has none (its bankruptcy shows in the company status and in its register-change events). Sole traders (enskild näringsverksamhet, trgovac pojedinac), enterprises of natural persons (eenmanszaak / entreprise individuelle), sole proprietorships (enkeltmandsvirksomhed) and estates are never served. Denmark has no share capital, and its status includes the register's bankruptcy state.
- **Insolvency (`insolvency_search`, `insolvency_check`):** corporate only, twelve markets (FR, DE, GB, AT, CH, NO, FI, US, NL, DK, HR, SE). Personal/consumer insolvency is never returned. Spain's concursal data is on `records_search` (`GET /search`), not `insolvency_search`.
- **Monitoring (`monitors`, `monitor`, `monitor_create`, `monitor_delete`):** ES, IE, PL, FI, SE, BE, HR, DK; alerts on status changes, dissolutions, sanctions matches and corporate events (ES and FI/SE/BE/HR/DK).
- **Sanctions screening (`sanctions_screen*`):** beta.
- **PEP hits (`sanctions_screen(name, include_pep=True)`):** beta, Spain only.
- **Norway:** no corporate-event stream (`events_*` returns empty for NO, and for IE and PL).
- **Finland:** company records only (`people_search` returns empty for FI; `events_*` returns register-change events, dated when first seen in the register data and none before 2026-09-30; `monitor_create` accepts it). Its insolvency notices are linked by business ID.
- **Sweden:** company records only (`people_search` returns empty for SE; `events_*` returns register-change events; `monitor_create` accepts it). Corporate insolvency notices (konkurs, företagsrekonstruktion, ackordsförhandling; updated weekly, no court, case number or source link, proceedings that ended before collection not included) are on `insolvency`, linked by organisationsnummer.
- **Croatia:** company records only (`people_search` returns empty for HR; `events_*` returns register-change events, including share capital; `monitor_create` accepts it). Corporate insolvency notices (court decisions on bankruptcy, shortened bankruptcy and pre-bankruptcy proceedings, with court and case number where the register states them; only companies still on the register) are linked by MBS. A Croatian company is found by MBS (`company_number`), OIB (`oib`) or the VAT alias (`vat=HR` plus the OIB).
- **Belgium:** company records only (`people_search` returns empty for BE; `events_*` returns register-change events; `monitor_create` accepts it). Belgium is not one of the twelve insolvency markets: its bankruptcy shows in the company status and in its register-change events. A Belgian company is found by enterprise number (`company_number`, the dots and spaces optional) or the VAT alias (`vat=BE` plus the ten digits).
- **Denmark:** company records only (`people_search` returns empty for DK; `events_*` returns register-change events; `monitor_create` accepts it). Corporate insolvency notices (konkurs and tvangsakkord decisions from CVR credit information, dated by the decision, no court or case number) are linked by CVR number. Contains CVR data (Erhvervsstyrelsen), CC BY 4.0. A Danish company is found by CVR number (`company_number`, spaces and hyphens optional; the mod-11 check is advisory) or the VAT alias (`vat=DK` plus the eight digits).

## Get a key

Free at https://www.prometiam.com/signup, no card required. Docs: https://www.prometiam.com/risk-api/docs. Support: support@prometiam.com.
