> For the complete documentation index, see [llms.txt](https://help.bizmachine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.bizmachine.com/api-a-integrace/api-endpointy/endpoint-events.md).

# Endpoint events - obchodní události firmy

*Aktualizováno: 30. července 2026*

```
GET /{dataset}/v3/events
```

Obchodní události firmy - vyhraná výběrová řízení, publikované smlouvy, mediální zmínky a další signály aktivity. Vhodné pro monitoring cílových firem nebo jako trigger pro automatizované akce v CRM.

***

## Jaké informace tento endpoint obsahuje

Každá událost obsahuje:

* **Předmět a text** - krátký popis (`subject`) a plný text události (`text`)
* **Kategorii** - typ události (viz přehled níže)
* **Datum** - kdy událost proběhla (`startedAt`) a kdy byla publikována (`publishedAt`)
* **Zdroj** - URL původního zdroje (registr smluv, média…)
* **Entity** - firmy zapojené do události (s IČO a názvem)
* **Závažnost** - `severity` (integer; 0, 1 nebo 2 - vyšší = závažnější)

### Kategorie událostí

> Dostupné kategorie se liší napříč trhy. Aktuální přehled najdete v pokročilém filtrování v Prospectoru, nebo se obraťte na <support@bizmachine.com>.

* Smlouvy publikované v registru smluv
* Vyhraná výběrová řízení (tendry)
* Mediální zmínky
* Publikace finančních zpráv (účetní závěrky, výroční zprávy)
* Výročí firem
* Nové nebo ukončené pracovní inzeráty
* Změny ve vedení (příchod nebo odchod jednatele, prokuristy)
* Změny vlastníků a statutárních zástupců
* Nové pobočky nebo změna adresy

Kompletní seznam kategorií dostupný v Prospectoru v pokročilém filtrování - sekce [Signály](https://help.bizmachine.com/pokrocile-funkce/firemni-signaly-a-upozorneni). Kategorie se průběžně rozšiřují.

### Kdy tento endpoint použít

* Monitorujete obchodní aktivitu cílových firem (nové smlouvy, zakázky)
* Hledáte trigger pro oslovení (firma právě vyhrála zakázku)
* Sledujete změny ve vlastnické struktuře nebo vedení cílových firem
* Monitorujete nábor (firma začala nebo ukončila inzerci pracovních míst)
* Stavíte alert systém nad změnami ve firmách

### Kdy použít jiný endpoint

| Potřebujete                            | Použijte místo toho |
| -------------------------------------- | ------------------- |
| Rizikové signály (insolvence, exekuce) | `risks` (v4)        |
| Celkový stav vlastnické struktury      | `owners` (v4)       |
| Pravidelné sledování vývoje metrik     | `metrics` (v3)      |

### Dostupnost

Endpoint je dostupný pro datasety: **cz, sk, pl, de**. Dostupné kategorie signálů se pro každý dataset liší.

***

## Technické informace

{% openapi src="/files/XsgqAcv6XJjIzqRU0Ubr" path="/{dataset}/v3/events" method="get" %}
[api-spec.temp.json](https://2865951599-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9IXbHwc2ctAHDxOoCdoX%2Fuploads%2Fgit-blob-de88966fec10805d50f17dc1d05ba0ecb23e8eb2%2Fapi-spec.temp.json?alt=media)
{% endopenapi %}

### Na co si dát pozor

* `startedAt` = datum události, `publishedAt` = datum zveřejnění (může být pozdější), `updatedAt` = datum poslední aktualizace záznamu.
* `summary` není přítomno u všech kategorií - např. u Vyhraný tendr klíč v odpovědi chybí. Vždy ověřte přítomnost klíče.

***

## Instrukce pro AI agenty

Zkopírujte tento blok a předejte ho agentovi - popisuje, jak endpoint správně používat.

```
## BizMachine API: events endpoint

Purpose: Returns business events for a company — won tenders, published contracts, media mentions,
and other activity signals. Useful for company monitoring and sales triggers.

When to use:
- You want to monitor business activity of target companies (new contracts, tenders)
- You need a trigger signal for outreach (company just won a tender, appeared in media)
- You are building an alert system for changes in target companies

When NOT to use:
- You need risk signals (insolvency, enforcement) → use risks (v4)
- You need ownership changes → use owners (v4)

URL:
  GET https://api.bizmachine.com/{dataset}/v3/events

Required:
  - Path: dataset — "cz", "sk", "pl", "de" (event categories differ per dataset)
  - Header: X-Api-Key: {api_key}

Optional:
  - Query: Company.NationalIn — filter by IČO
  - Query: Category.Code — contract-publication / tender-won / media / fin-report-publ / company-anniversary
  - Query: Company.Role — role of the company in the event
  - Query: Company.OnlyFollowed — true/false, only followed companies
  - Query: Source.Code — filter by source code
  - Query: Started.From / Started.To — date range (e.g. 2026-04-27T00:00:00Z)
  - Query: Updated.From / Updated.To — filter by update date
  - Query: Limit — default 200, max 250
  - Query: Offset — pagination

Key response fields (per item in data[]):
  data[i].data.uniqueId                — event ID
  data[i].data.subject                 — short description
  data[i].data.summary                 — summary (not present for all categories)
  data[i].data.text                    — full text
  data[i].data.url                     — source URL
  data[i].data.publishedAt             — publication timestamp (ISO 8601)
  data[i].data.startedAt               — event timestamp (ISO 8601)
  data[i].data.updatedAt               — last update timestamp (ISO 8601)
  data[i].data.categories[0].code      — event category code
  data[i].data.categories[0].name      — event category name
  data[i].data.severity                — severity integer (0, 1 or 2 — higher = more significant)
  data[i].data.entities[0].nationalIn  — IČO of company involved
  data[i].data.entities[0].name        — name of company involved
  data[i].data.entities[0].type        — entity type ("Company")

Gotchas:
  - startedAt is the event date, publishedAt is when it was published (can be later), updatedAt is when the record was last updated
  - summary is not present for all categories (e.g. tender-won, media, fin-report-publ); always check key presence

Event categories (list may change):
  - contract-publication  — government contract registry (company as supplier)
  - tender-won            — won public tender
  - media                 — media mention
  - fin-report-publ       — financial report publication (annual report, financial statements)
  - company-anniversary   — company anniversary

Typical workflow (sales trigger monitoring):
  1. events?Company.NationalIn={nationalIn}&Category.Code=tender-won → check for recent wins
  2. events?Company.NationalIn={nationalIn}&Started.From=2026-01-01 → get recent activity
```

***

Potřebujete pomoc? Ozvěte se na <support@bizmachine.com>