API Reference

Send your key in the X-API-Key header on every request. A key passed as a Bearer token is rejected with 401.

• Live keys carry the markets, features and limits in your agreement.
• Sandbox keys are for evaluation: they expire after 30 days unless you set a shorter term, and bulk and delta return 403.

Keys are shown once when created. Store them securely and revoke any key you no longer use.

Search companies:

curl -H "X-API-Key: YOUR_KEY" \
  "https://api.amberbook.eu/api/v1/companies?countries=CZ&limit=5"

List responses are paginated with offset and limit and return a total. On a filter nobody has run recently the first response can carry a planner estimate: total_is_estimate is then true, and a repeat request a few seconds later returns the exact count. Company IDs are UUIDs, timestamps are ISO 8601 UTC, and monetary values are EUR unless noted.

To keep a full copy of the dataset in your own warehouse, load a bulk snapshot once, then apply the delta feed. Snapshots are written nightly per country for the companies, events and financials datasets and kept for 3 days. Bulk and delta are enabled per contract.

1. List the newest snapshots: GET /api/v1/delivery/bulk, optionally with country and dataset. Each entry carries row_count, per-field field_fill counts, a sha256 and size for its file, and a cursor.
2. Download it: GET /api/v1/delivery/bulk/{id}/download answers 303 with a link valid for 5 minutes, so follow redirects and download straight away. The file is gzipped JSON lines, one record per line.
3. Pass the snapshot's cursor as since to GET /api/v1/delivery/delta/companies (limit up to 5000, optional country). Send each next_cursor back as since until has_more is false, and store the last one for the next run. A row with deleted: true removes that company.
4. Company events follow the same loop on GET /api/v1/delivery/delta/events. Treat event_type as an open set.

curl -H "X-API-Key: YOUR_KEY" "https://api.amberbook.eu/api/v1/delivery/bulk?country=SK"
curl -L -H "X-API-Key: YOUR_KEY" -o sk.jsonl.gz \
  "https://api.amberbook.eu/api/v1/delivery/bulk/SNAPSHOT_ID/download"
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.amberbook.eu/api/v1/delivery/delta/companies?since=CURSOR&limit=1000"

The stable key is company_id; country_code plus registry_id identify the company in its national register. Cursors are opaque; an empty page returns your cursor unchanged. Deletions are kept for 35 days, so a cursor older than that should restart from the newest snapshot. A malformed cursor returns 422.

Manage endpoints, secrets and test deliveries from Account - Webhooks, or with the calls below.

Register an HTTPS endpoint with POST /api/v1/webhooks and a body of url, optional event_types (empty means every event) and channel_type (generic, slack or teams). The response contains the signing secret once; store it. POST /api/v1/webhooks/{id}/rotate issues a new one, and POST /api/v1/webhooks/{id}/test sends a test event; GET /api/v1/webhooks/{id}/deliveries lists recent delivery attempts.

Events: watchlist.ownership_change, watchlist.insolvency_status_change, watchlist.debt_flag_onset, watchlist.sanctions_flag_change, watchlist.legal_proceeding, watchlist.financial_filing, watchlist.news_mention, watchlist.new_company_in_saved_view, watchlist.member_added and watchlist.test. The name is also sent in X-Amberbook-Event.

Every generic delivery carries X-Amberbook-Signature: sha256=<hex>, the HMAC-SHA256 of the raw request body under your secret. Verify it before parsing, and use X-Amberbook-Delivery-Id to ignore a redelivery. A non-2xx answer is retried with backoff for up to about two days.

import hashlib, hmac

def verified(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Limits are set in your agreement. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit, the API returns 429 with a Retry-After header - wait that many seconds before retrying.