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

# Endpoint contacts - kontakty na firmu a osoby

*Aktualizováno: 30. července 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>