> 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-aggregated-data.md).

# Endpoint aggregated-data - profil firmy

*Aktualizováno: 30. července 2026*

## Endpoint: aggregated-data

```
GET /{dataset}/v4/companies/{nationalIn}/aggregated-data
```

Základní endpoint pro data o firmě. Vrací kompletní profil - identifikaci, adresu, všeobecné kontakty firmy, NACE, indikátory a souhrn 25 metrik (pouze poslední hodnoty, bez časových řad).

***

### Jaké informace tento endpoint obsahuje

`aggregated-data` vám v jednom volání dá odpověď na základní otázky o firmě:

* **Kdo to je?** Název, IČO, DIČ, právní forma, datum vzniku, status (aktivní / v likvidaci…), popis firmy
* **Kde sídlí?** Adresa s GPS souřadnicemi, hierarchie lokalit (obec → okres → kraj)
* **Jaké jsou všeobecné kontakty?** Web, e-mail, telefon, LinkedIn, Facebook
* **Jak velká je?** Pásmo počtu zaměstnanců, tržby, aktiva, EBIT
* **Jak roste?** Skóre aktivity, růstu a dostupnosti (0-100)
* **Čím se zabývá?** Primární NACE kód + ostatní kategorie
* **Má rizika?** Počet rizikových signálů (insolvence, exekuce…)

#### Kdy tento endpoint použít

* Potřebujete základní profil firmy před obchodní schůzkou nebo analýzou
* Obohacujete záznamy v CRM (enrich) - název, adresa, odvětví, velikost
* Jako první volání v pipeline: zjistíte co firma je, pak se rozhodnete co dál volat
* Potřebujete rychlý přehled metrik bez historických časových řad

#### Kdy použít jiný endpoint

| Potřebujete                      | Použijte místo toho |
| -------------------------------- | ------------------- |
| Historii metrik (víceleté řady)  | `metrics` (v3)      |
| Detailní rizikové signály        | `risks` (v4)        |
| Vlastnickou strukturu s historií | `owners` (v4)       |
| Detailní indikátory s drivery    | `indicators` (v3)   |
| Detailní finanční výkazy         | `financials` (v3)   |

#### Dostupnost

Endpoint je dostupný pro všechny datasety: **cz, sk, hu, pl, de**.

***

### Technické informace

{% openapi src="/files/XsgqAcv6XJjIzqRU0Ubr" path="/{dataset}/v4/companies/{nationalIn}/aggregated-data" 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

* `employees` nemá přesnou hodnotu - jen pásmo v `category`. Přesný počet zaměstnanců není v tomto endpointu dostupný.
* `contacts.website` má pole `.value` (ne `.url`) - stejný vzor jako `email` a `phoneNumber`.
* `contacts` = všeobecné kontakty firmy (web, e-mail, telefon, LinkedIn, Facebook) - **ne osobní kontakty** na konkrétní osoby.
* `indicators.*` může být `null` na úrovni celého objektu (nejen `.value`) - vždy ověřte, že objekt existuje, než přistoupíte k `.value`.
* `selfDeclaredCategories` může mít 400+ položek → velký payload.
* `risks` je `null` pokud firma nemá rizika (ne prázdné pole).
* Endpoint obsahuje souhrn \~25 metrik bez historie. Pro kompletních 64 metrik s víceletými řadami použijte `metrics` (v3).

***

### Instrukce pro AI agenty

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

```
## BizMachine API: aggregated-data endpoint

Purpose: Returns a complete company profile in a single API call — identity, address,
company contacts, NACE codes, key metrics (latest values only), and business indicators.

When to use:
- You have a company's national identifier (IČO) and need a full profile
- You are enriching CRM records (name, address, industry, size, contacts)
- As the entry point in a pipeline before deciding which other endpoints to call
- You need a quick metrics overview without historical time series

When NOT to use:
- Historical metrics (multi-year time series) → use /metrics (v3)
- Detailed risk signals → use /risks (v4)

URL:
  GET https://api.bizmachine.com/{dataset}/v4/companies/{nationalIn}/aggregated-data

Required:
  - Path: dataset — "cz", "sk", "hu", "pl" or "de"
  - Path: nationalIn — company national ID / IČO (e.g. "27082440")
  - Header: X-Api-Key: {api_key}

Optional:
  - Header: Accept-Language: CS  (for Czech field names and values)

Key response fields:
  data.basicInfo.nationalIn          — company ID (IČO)
  data.basicInfo.name                — company name
  data.basicInfo.vatIn               — VAT number
  data.basicInfo.health.code         — company status ("inbusiness", "dissolved", ...)
  data.basicInfo.establishedAt       — founding date (ISO 8601)
  data.basicInfo.legalForm.name      — legal form
  data.basicInfo.selfDescription     — company description
  data.address.text                  — full address
  data.address.city                  — city
  data.address.postalCode            — postal code
  data.address.coordinates           — GPS (latitude, longitude)
  data.contacts.website.value        — company website
  data.contacts.email.value          — company email
  data.contacts.phoneNumber.value    — company phone
  data.contacts.linkedIn.value       — LinkedIn profile URL
  data.contacts.facebook.value       — Facebook profile URL
  data.metrics.revenue               — revenue {value, currency} or band in category
  data.metrics.employees             — headcount: band ONLY in category.name (value is always null)
  data.metrics.ebit                  — EBIT {value, currency}
  data.metrics.ebitda                — EBITDA {value, currency}
  data.metrics.assetsTotal           — total assets {value, currency}
  data.metrics.revenueGrowth         — revenue growth (ratio)
  data.metrics.personnelCost         — personnel costs {value, currency}
  data.metrics.locationCount         — number of operating locations
  data.metrics.openJobCountCurrentTotal — current open job positions
  data.metrics.riskCount             — number of risks (null if none)
  data.indicators.activity.value     — activity score (0–100)
  data.indicators.growth.value       — growth score (0–100)
  data.indicators.reachability.value — reachability score (0–100)
  data.nace.primary.code             — primary NACE code
  data.nace.primary.name             — NACE category name
  meta.prospector.link               — link to company profile in Prospector UI

Gotchas:
  - data.metrics.employees.value is ALWAYS null — exact headcount unavailable, band only
  - data.contacts.website.value — field is .value (not .url), consistent with email and phone
  - data.contacts = company contacts (web, email, phone, LinkedIn, Facebook) — NOT personal contacts
  - data.indicators.* can be null at the object level (not just .value) — always null-check the parent object before accessing .value
  - data.basicInfo.selfDeclaredCategories can have 400+ items → large payload
  - data.risks is null when no risks present (not an empty array)
  - data.metrics contains more fields than listed above — for full 64 metrics with history → combine with /metrics (v3)

Typical workflow (CRM enrichment):
  1. Call aggregated-data → get basic profile + metrics
  2. Call /metrics (v3) → get historical time series
  = complete profile in 2 API calls
```

***

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