# Endpoint aggregated-data — profil firmy

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


---

# 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-aggregated-data.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.