Endpoint aggregated-data - profil firmy

Kompletní profil firmy v jednom API volání - identifikace, adresa, všeobecné kontakty firmy, NACE, indikátory a souhrn 25 metrik.

Aktualizováno: 30. července 2026

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

Gets aggregated data for company identified by nationalIn.

get

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

Authorizations

X-Api-KeystringRequired

Authorization header which caries ApiKey information. Copy value generated using ApiKey endpoint.
Example: abcdefgh-1234-5678-90yz-ijklmnopqrs

Path parameters

nationalInstringRequired

National identifier of the company.

datasetstringRequired

Responses

200

Success

application/json

Envelope that contains aggregated data and meta information.

get/{dataset}/v4/companies/{nationalIn}/aggregated-data

GET /{dataset}/v4/companies/{nationalIn}/aggregated-data HTTP/1.1
Host: api.bizmachine.com
X-Api-Key: YOUR_API_KEY
Accept: */*

200

Success

{
  "data": {
    "companyUniqueId": "text",
    "address": {
      "uniqueId": "text",
      "text": "text",
      "streetName": "text",
      "streetNumber": "text",
      "city": "text",
      "postalCode": "text",
      "coordinates": {
        "latitude": 1,
        "longitude": 1
      },
      "locality": {
        "code": "text",
        "name": "text",
        "types": [
          "text"
        ],
        "parent": {
          "code": "text",
          "name": "text",
          "types": [
            "text"
          ],
          "parent": {
            "code": "text",
            "name": "text",
            "types": [
              "text"
            ],
            "parent": "[Circular Reference]"
          }
        }
      },
      "countrySpecific": {
        "cz": {
          "municipalityPart": "text",
          "cityBorough": "text",
          "cityDistrict": "text",
          "orientationNumber": "text",
          "houseNumber": 1,
          "isEvidenceNumber": true,
          "ruian": {
            "addressPointNumber": 1,
            "buildingNumber": 1,
            "streetNumber": 1,
            "cityBoroughNumber": 1,
            "cityDistrictNumber": 1,
            "municipalityPartNumber": 1,
            "municipalityNumber": 1,
            "basicSettlementUnitNumber": 1,
            "cadasterAreaNumber": 1,
            "url": "https://example.com",
            "plotNumber": 1
          },
          "purposeTypes": [
            {
              "code": "text",
              "name": "text"
            }
          ]
        },
        "sk": {
          "purposeTypes": [
            {
              "code": "text",
              "name": "text"
            }
          ]
        }
      },
      "_meta": {
        "hash": "text",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      }
    },
    "basicInfo": {
      "nationalIn": "text",
      "identifiers": {
        "ANY_ADDITIONAL_PROPERTY": {
          "value": "text",
          "name": "text",
          "formattedValue": "text",
          "description": "text"
        }
      },
      "name": "text",
      "vatIn": "text",
      "isVerifiedVatPayer": true,
      "taxIn": "text",
      "establishedAt": "2026-01-01T00:00:00.000Z",
      "disestablishedAt": "2026-01-01T00:00:00.000Z",
      "closedAt": "2026-01-01T00:00:00.000Z",
      "logo": {
        "url": "text"
      },
      "keywords": [
        "text"
      ],
      "registration": {
        "court": {
          "name": "text"
        },
        "fileNumber": "text",
        "recordUrl": "text",
        "createdAt": "2026-01-01T00:00:00.000Z"
      },
      "health": {
        "code": "text",
        "name": "text"
      },
      "legalForm": {
        "code": "text",
        "name": "text",
        "parent": {
          "code": "text",
          "name": "text",
          "parent": {
            "code": "text",
            "name": "text",
            "parent": "[Circular Reference]"
          }
        }
      },
      "institutionalSector": {
        "code": "text",
        "name": "text",
        "parent": {
          "code": "text",
          "name": "text",
          "parent": {
            "code": "text",
            "name": "text",
            "parent": "[Circular Reference]"
          }
        }
      },
      "selfDescription": "text",
      "selfDeclaredCategories": [
        {
          "code": "text",
          "name": "text",
          "parent": {
            "code": "text",
            "name": "text",
            "parent": {
              "code": "text",
              "name": "text",
              "parent": "[Circular Reference]"
            }
          }
        }
      ],
      "_meta": {
        "hash": "text",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      }
    },
    "metrics": {
      "revenue": {
        "value": {
          "amount": 1,
          "currency": "text"
        },
        "category": {
          "lowerBound": {
            "amount": 1,
            "currency": "text"
          },
          "upperBound": {
            "amount": 1,
            "currency": "text"
          },
          "code": "rev_1500M-inf",
          "name": "1 500 000 000 KĂ„Ĺ¤ a vice"
        },
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "assetsTotal": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "netProfitMargin": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "revenueGrowth": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "isExporter": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "isImporter": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "employees": {
        "category": {
          "lowerBound": 1,
          "upperBound": 1,
          "code": "rev_1500M-inf",
          "name": "1 500 000 000 KĂ„Ĺ¤ a vice"
        },
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "connectedCompaniesCount": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "registeredCapital": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "ebit": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "ebitda": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "ebitMargin": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "vehiclesOperatedTotal": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "vehiclesOwnedTotal": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "vehiclesRegistered12Months": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "personnelCost": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "openJobCountCurrentTotal": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "latestFinancialsAvailable": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "publicOwnershipShare": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "privateOwnershipShare": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "foreignOwnershipShare": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "eshopCount": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "locationCount": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "riskCount": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "businessCardsCount": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "ownerAge": {
        "name": "text",
        "type": "CategoryValueCurrency",
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z"
      },
      "_meta": {
        "hash": "text",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      }
    },
    "nace": {
      "primary": {
        "code": "text",
        "name": "text"
      },
      "other": [
        {
          "code": "text",
          "name": "text"
        }
      ],
      "_meta": {
        "hash": "text",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      }
    },
    "contacts": {
      "phoneNumber": {
        "uniqueId": "text",
        "value": "text",
        "valueFormatted": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "email": {
        "uniqueId": "text",
        "value": "text",
        "valueFormatted": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "website": {
        "uniqueId": "text",
        "value": "text",
        "valueFormatted": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "linkedIn": {
        "uniqueId": "text",
        "value": "text",
        "valueFormatted": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "facebook": {
        "uniqueId": "text",
        "value": "text",
        "valueFormatted": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "twitter": {
        "uniqueId": "text",
        "value": "text",
        "valueFormatted": "text",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "_meta": {
        "hash": "text",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      }
    },
    "indicators": {
      "activity": {
        "name": "text",
        "value": 1,
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z",
        "drivers": [
          {
            "code": "text",
            "name": "text",
            "weight": 1
          }
        ]
      },
      "covid19": {
        "name": "text",
        "value": 1,
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z",
        "drivers": [
          {
            "code": "text",
            "name": "text",
            "weight": 1
          }
        ]
      },
      "growth": {
        "name": "text",
        "value": 1,
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z",
        "drivers": [
          {
            "code": "text",
            "name": "text",
            "weight": 1
          }
        ]
      },
      "reachability": {
        "name": "text",
        "value": 1,
        "validFrom": "2026-01-01T00:00:00.000Z",
        "validTo": "2026-01-01T00:00:00.000Z",
        "drivers": [
          {
            "code": "text",
            "name": "text",
            "weight": 1
          }
        ]
      },
      "_meta": {
        "hash": "text",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      }
    },
    "risks": {
      "current": [
        {
          "name": "text",
          "code": "text",
          "parent": {
            "code": "text",
            "name": "text",
            "parent": {
              "code": "text",
              "name": "text",
              "parent": {
                "code": "text",
                "name": "text",
                "parent": "[Circular Reference]"
              }
            }
          },
          "severity": 1,
          "validFrom": "2026-01-01T00:00:00.000Z",
          "validTo": "2026-01-01T00:00:00.000Z",
          "connectedCompanies": [
            {
              "uniqueId": "text",
              "name": "text"
            }
          ],
          "sources": [
            {
              "code": "text",
              "name": "text"
            }
          ]
        }
      ],
      "_meta": {
        "hash": "text",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      }
    }
  },
  "meta": {
    "prospector": {
      "link": "text"
    },
    "hash": "text",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

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

PředchozíEndpoint metrics - přehled metrik

DalšíEndpoint suggest - vyhledávání firem

Poslední aktualizace před 25 dny