# Endpoint events — obchodní události firmy

*Aktualizováno: 28. dubna 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.bizmachine.com/api-a-integrace/api-endpointy/endpoint-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.