> 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/en/api-and-integrations/api-endpoints/endpoint-contacts.md).

# Endpoint contacts: company and personal contacts

The contacts endpoint returns phone numbers, emails, websites and LinkedIn profiles for a company and for the people in it, each with a confidence value.

*Updated: 7 October 2026*

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

Contacts for a company and for specific people in it: phone numbers, emails, LinkedIn profiles, websites. The endpoint returns company contacts (assigned directly to the company) and personal contacts (assigned to a specific person with a role).

***

### What this endpoint returns

Each contact in the response contains:

* **Type**: Phone, Email, Website, SocialMedia (LinkedIn, Facebook and others), Fax
* **Value**: `value` (raw, for example `00420123456789`) and `valueFormatted` (formatted and readable, for example `+420 123 456 789`)
* **Confidence**: `confidence` (0 to 1), how sure we are that the contact is correct
* **Sources**: where the contact comes from (the company website, Firmy.cz, LinkedIn and others) and when it was last verified
* **Person**: for personal contacts, a `person` object with the name, roles and department

#### Company vs. personal contacts

| Contact type                      | `person` object | `isPersonal` |
| --------------------------------- | --------------- | ------------ |
| Company (assigned to the company) | absent          | `false`      |
| Personal (assigned to a person)   | present         | `true`       |

Company contacts are general (reception, the info email, the company website). Personal contacts are linked to a specific person with a position in the company. A contact with an unclear personal link (for example `pepa@firma.cz`) can be assigned as both a company and a personal contact.

#### When to use this endpoint

* You need an email or phone number for a specific person at a target company
* You are exporting contacts to a CRM or an automation tool (Clay, Make.com, n8n)
* You are looking for the LinkedIn profile of a specific person in a company

#### When to use a different endpoint

| You need                                                           | Use instead                                                                                          |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| One company contact of each type is enough (website, email, phone) | `aggregated-data` (v4), the `data.contacts` section, which returns the one best contact of each type |
| An overview of key people without contact details                  | `owners` (v4), `statutories` (v3)                                                                    |

#### Availability

The endpoint is available for all datasets: **cz, sk, hu, pl, de**.

It is available as a single-company request (one company by Company ID) and as a collection request (several companies at once).

***

### Technical details

{% openapi src="/files/FGwu42o2gqsEWtcATX3u" path="/{dataset}/v4/companies/{nationalIn}/contacts" method="get" %}
[api-spec.temp.json](https://247275268-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYkl7SJ14Nk0vzhVx7upl%2Fuploads%2Fgit-blob-f3abeffbb2534d765afc74352238d1f9ef6bc845%2Fapi-spec.temp.json?alt=media)
{% endopenapi %}

#### What to watch out for

* The `person` object is optional. Contacts without a linked person do not have it at all (the key is missing, not set to null). Always check that the `person` key exists before you access `person.name` or `person.roles`.
* `isPersonal: true` in the `contact` object means a personal contact. You can use it as a quick filter.
* `confidence` is a decimal number from 0.00 to 1.00 (not a percentage). A value of 0.85 means 85 percent confidence.
* The default `Limit` is 200 *(as of July 2026)*. Large companies have hundreds of contacts, so filter by type or use pagination.
* `value` is the raw format (`00420XXXXXXXXX`) and `valueFormatted` is the readable one (`+420 XXX XXX XXX`).
* SocialMedia contacts also carry `socialMediaType.code` (for example `"linkedin"`).

***

### Instructions for AI agents

Copy this block and give it to your agent. It describes how to use the endpoint correctly.

```
## 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
```

***

Need help? Write to <support@bizmachine.com>