Endpoint contacts - kontakty na firmu a osoby

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

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ř. [phone])

• 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ř. [e-mail]) 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

Kontakty na firmu a osoby

get

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

Authorizations

X-Api-KeystringRequired

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

Path parameters

datasetstringRequired

nationalInstringRequired

IČO firmy.

Query parameters

Typesstring[] · nullableOptional

Filtr typů kontaktů: Phone, Fax, Email, Website, Other, SocialMedia.

IsPrimaryboolean · nullableOptional

Pouze primární kontakty.

IsPrivateboolean · nullableOptional

Filtr soukromých/veřejných kontaktů.

Sourcesstring[] · nullableOptional

Filtr zdrojů (kód zdroje).

LastCheck.Fromstring · date-time · nullableOptional

Kontakty ověřené od tohoto data.

LastCheck.Tostring · date-time · nullableOptional

Kontakty ověřené do tohoto data.

Updated.CreatedFromstring · date-time · nullableOptional

Záznamy vytvořené od tohoto data.

Updated.CreatedTostring · date-time · nullableOptional

Záznamy vytvořené do tohoto data.

Limitinteger · int32 · max: 250 · nullableOptional

Počet výsledků. Výchozí 200, max 250.

Offsetinteger · int32 · nullableOptional

Stránkování.

SortBystring · nullableOptional

Řazení výsledků.

Responses

200

Success

No content

get/{dataset}/v4/companies/{nationalIn}/contacts

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

200

Success

No content

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 [e-mail]