> 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

Kontakty na firmu a osoby - telefony, e-maily, LinkedIn profily. Vrací firemní i osobní kontakty.

*Aktualizováno: 7. října 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 automatizaci (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

* Objekt `person` nemusí být v odpovědi vůbec - kontakty bez navázané osoby ho 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 to 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 to 1 (not 0 to 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>