# Endpoint contacts — kontakty na firmu a osoby

*Aktualizováno: 28. dubna 2026*

```
GET /{dataset}/v4/companies/{nationalIn}/contacts
```

Kontakty na firmu i konkrétní osoby — telefony, e-maily, LinkedIn profily, weby. Vrací firemní kontakty (přiřazené přímo firmě) i osobní kontakty (přiřazené konkrétní osobě s rolí).

***

## Jaké informace tento endpoint obsahuje

Každý kontakt v odpovědi obsahuje:

* **Typ** — Phone, Email, Website, SocialMedia (LinkedIn, Facebook…), Fax
* **Hodnotu** — `value` (raw, např. `00420123456789`) a `valueFormatted` (naformátovaná, čitelná, např. `+420 123 456 789`)
* **Jistotu** — `confidence` (0–1): jak jistí jsme si správností kontaktu
* **Zdroje** — odkud kontakt pochází (firemní web, Firmy.cz, LinkedIn…) a kdy byl naposledy ověřen
* **Osobu** — u osobních kontaktů je přítomen `person` objekt s jménem, rolemi a oddělením

### Firemní vs. osobní kontakty

| Typ kontaktu              | `person` objekt | `isPersonal` |
| ------------------------- | --------------- | ------------ |
| Firemní (přiřazený firmě) | chybí           | `false`      |
| Osobní (přiřazený osobě)  | přítomen        | `true`       |

Firemní kontakty jsou obecné (recepce, info e-mail, web firmy). Osobní kontakty jsou navázány na konkrétní osobu s pozicí ve firmě. Kontakt s nejasnou osobní vazbou (např. `pepa@firma.cz`) může být přiřazen zároveň jako firemní i jako osobní.

### Kdy tento endpoint použít

* Potřebujete e-mail nebo telefon na konkrétní osobu v cílové firmě
* Exportujete kontakty do CRM nebo nástroje pro outreach (Clay, Make.com, N8N)
* Hledáte LinkedIn profil konkrétní osoby ve firmě

### Kdy použít jiný endpoint

| Potřebujete                                                          | Použijte místo toho                                                                           |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Stačí vám jeden kontakt firmy od každého typu (web, e-mail, telefon) | `aggregated-data` (v4) — sekce `data.contacts` — vrací jeden nejlepší kontakt od každého typu |
| Přehled klíčových osob bez kontaktů                                  | `owners` (v4), `statutories` (v3)                                                             |

### Dostupnost

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

Dostupný jako single request (pro jednu firmu podle IČO) i jako collection request (pro více firem najednou).

***

## Technické informace

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

* `person` objekt je nullable — kontakty bez navázané osoby ho vůbec nemají (chybí klíč, nejde o null). Vždy ověřte přítomnost klíče `person`, než přistupujete k `person.name` nebo `person.roles`.
* `isPersonal: true` v `contact` objektu = osobní kontakt. Lze použít jako rychlý filtr.
* `confidence` je desetinné číslo v rozsahu 0.00–1.00 (nikoliv procenta). Hodnota 0.85 = 85% jistota.
* Výchozí `Limit` je 200 — velké firmy mají stovky kontaktů. Filtrujte typem nebo používejte stránkování.
* `value` je raw formát (`00420XXXXXXXXX`), `valueFormatted` je čitelný (`+420 XXX XXX XXX`).
* Pro SocialMedia kontakty je k dispozici `socialMediaType.code` (např. `"linkedin"`).

***

## Instrukce pro AI agenty

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

```
## BizMachine API: contacts endpoint

Purpose: Returns contacts for a company — company-level contacts (phone, email, website)
and personal contacts linked to specific people with roles and departments.

When to use:
- You need an email or phone for a specific person at a company
- You are enriching CRM records with personal contact details (decision-makers)
- You need LinkedIn profiles of people at a target company

When NOT to use:
- You need general company contacts (web, company email) → use aggregated-data (data.contacts)
- You need a list of key people without contact details → use owners (v4)

URL:
  GET https://api.bizmachine.com/{dataset}/v4/companies/{nationalIn}/contacts

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

Optional:
  - Query: Types — Phone, Fax, Email, Website, Other, SocialMedia
  - Query: IsPrimary — true/false
  - Query: Limit — default 200, max 250
  - Query: Offset — pagination

Key response fields (per item in data[]):
  data[i].data.company.nationalIn             — company IČO
  data[i].data.person                         — ABSENT for company contacts, present for personal
  data[i].data.person.name.text               — full name (e.g. "Jan Novák")
  data[i].data.person.name.firstName          — first name
  data[i].data.person.name.lastName           — last name
  data[i].data.person.roles[0].text           — job title / role
  data[i].data.person.departments[0].code     — department code
  data[i].data.contact.type                   — Phone / Email / Website / SocialMedia / Fax / Other
  data[i].data.contact.value                  — raw contact value
  data[i].data.contact.valueFormatted         — human-readable value
  data[i].data.contact.isPrimary              — boolean
  data[i].data.contact.isPersonal             — true = personal contact, false = company contact
  data[i].data.contact.confidence             — 0–1
  data[i].data.contact.sources[0].url         — source URL
  data[i].data.contact.sources[0].lastCheckedAt — last verification timestamp (ISO 8601)
  data[i].data.contact.socialMediaType.code   — "linkedin", "facebook", etc. (SocialMedia only)

Gotchas:
  - data[i].data.person is ABSENT (key missing, not null) for company contacts — use key existence check
  - confidence is 0–1 (not 0–100) — 0.85 = 85% confidence
  - Default Limit is 200 — large companies may have hundreds of contacts; use Types filter or pagination
  - value is raw format; use valueFormatted for display
  - socialMediaType only present on SocialMedia type contacts

Typical workflow:
  1. suggest → get nationalIn
  2. contacts?Types=Email → get email contacts
  3. contacts?Types=SocialMedia → get LinkedIn profiles
  4. Filter by isPersonal=true for personal contacts only
```

***

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-contacts.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.