# Datenmodell (https://webmetic.de/docs/api/datenmodell)

Ein Beispiel: Die Bergquell Mineralbrunnen GmbH besucht diese Woche dreimal Ihre Website. In der API ist das ein Unternehmen mit drei Sessions, und jede Session enthält ihre Seitenaufrufe. Personen kommen in den Besuchsdaten nicht vor.

Die API liefert nur Besuche, die Webmetic einem Unternehmen zugeordnet hat, und lässt alle anderen Besuche weg.

## Besuchsdaten [#besuchsdaten]

1. **Ihre Website**: Sie wählen die Website in jeder Anfrage mit dem Parameter `domain`.
2. **Session**: Jeder Besuch auf dieser Website ist eine Session mit eigener `session_id` und gehört zu genau einem Unternehmen.
3. **Seitenaufruf**: Jede Seite, die der Besuch aufgerufen hat, steht als Seitenaufruf im Feld `user_data` der Session.

Diese Kennungen verbinden die Objekte:

- `domain`: Ihre Website als Domain ohne `https://`, genau so geschrieben wie in Ihrem Konto. Bei jeder anderen Schreibweise antwortet die API mit `API_KEY_NOT_AUTHORIZED`. Besuche auf Subdomains wie `shop.ihre-website.de` zählen zu `ihre-website.de`.
- `company_id`: die Kennung eines Unternehmens als Zeichenkette, die gleich bleibt. Werten Sie den Aufbau der Kennung nicht aus und speichern Sie `company_url` als zweiten Schlüssel dazu.
- `session_id`: die Kennung eines Besuchs mit 26 Zeichen, die gleich bleibt und sich nach der Zeit sortieren lässt.
- `client_id`: die pseudonymisierte Kennung des Besuchers, die sich täglich ändert und je Konto verschieden ist. Über mehrere Tage hinweg verbindet sie deshalb keine Besuche.
- Seitenaufruf: Weil er keine eigene Kennung hat, erkennen Sie ihn an `session_id` und `timestamp`.

Alle Zeitstempel stehen in UTC, in API-Antworten ohne `Z` und in Webhook-Zustellungen mit `Z`. Mehr dazu unter [Zeiträume und Zeitzonen](https://webmetic.de/docs/api/zeitraeume-und-zeitzonen).

## Objekte und Verbindungen [#objekte-und-verbindungen]

| Objekt | Verbunden über | Endpunkt |
| --- | --- | --- |
| [Company](https://webmetic.de/docs/api/datenmodell/company) | `company_id` | [`/company`](https://webmetic.de/docs/api/referenz/visitor-intelligence/company), [`/company-sessions`](https://webmetic.de/docs/api/referenz/visitor-intelligence/company-sessions) |
| [Session](https://webmetic.de/docs/api/datenmodell/session) | `session_id`, dazu `company_id` des Unternehmens | [`/session`](https://webmetic.de/docs/api/referenz/visitor-intelligence/session) |
| [Page View](https://webmetic.de/docs/api/datenmodell/page-view) | `session_id`, ohne `company_id` | [`/session_user_data`](https://webmetic.de/docs/api/referenz/visitor-intelligence/session-user-data) |
| NACE-Code | Liste `nace_codes` im Unternehmen, in `/company_nace` eine Zeile pro Code mit `company_id` | [`/company_nace`](https://webmetic.de/docs/api/referenz/visitor-intelligence/company-nace) |
| [Besuchsarten](https://webmetic.de/docs/api/datenmodell/besuchsarten) | Unternehmen mit den passenden Sessions | [`/intensive-visits`](https://webmetic.de/docs/api/referenz/visitor-intelligence/intensive-visits), [`/returning-visits`](https://webmetic.de/docs/api/referenz/visitor-intelligence/returning-visits), [`/new-visits`](https://webmetic.de/docs/api/referenz/visitor-intelligence/new-visits) |
| [Contact](https://webmetic.de/docs/api/datenmodell/contact) | `company_id` in der Anfrage, `contact_id` in der Antwort | [`/contacts/search`](https://webmetic.de/docs/api/referenz/contacts/search), [`/contacts/reveal`](https://webmetic.de/docs/api/referenz/contacts/reveal) |
| [Credits](https://webmetic.de/docs/api/datenmodell/credits) | Ihr Konto, nicht die Website | [`/contacts/credits`](https://webmetic.de/docs/api/referenz/contacts/credits) |
| [Enrichment-Liste](https://webmetic.de/docs/api/datenmodell/enrichment-liste) | nur die Domain des Unternehmens | [`/enrichment/lists`](https://webmetic.de/docs/api/referenz/enrichment/lists), [`/enrichment/company`](https://webmetic.de/docs/api/referenz/enrichment/company) |
| Webhook-Ereignis | `data.company.company_id` und `data.visit.session_id` | [Webhooks](https://webmetic.de/docs/api/webhooks) |

Ansprechpartner tragen zwar den Namen ihres Unternehmens, aber keine `company_id`. Speichern Sie deshalb die `company_id`, mit der Sie gesucht haben. Die Suche funktioniert nur für Unternehmen, die eine Ihrer Websites besucht haben. Für alle anderen Unternehmen antwortet die API mit `COMPANY_NOT_IDENTIFIED`.

Ein Webhook-Ereignis enthält das Unternehmen in `data.company` und den Besuch mit seinen Seitenaufrufen in `data.visit`. Bei `segment.entered` stehen in `data.segment` `id` und `label` eines Segments aus dem Dashboard. Segmente selbst liefert die API nicht.

## Verschachtelte und flache Antworten [#verschachtelte-und-flache-antworten]

`/company-sessions` liefert jedes Unternehmen mit seinen Sessions und darin die Seitenaufrufe. Die Seiten der Antwort zählen dabei Unternehmen und nicht Sessions, wie unter [Paginierung](https://webmetic.de/docs/api/paginierung) beschrieben. `/company`, `/session` und `/session_user_data` liefern dieselben Ebenen einzeln als flache Listen.

Kein Endpunkt liefert ein Unternehmen nach seiner `company_id` oder eine Session nach ihrer `session_id`. Sie fragen immer eine Website und einen Zeitraum ab und wählen danach aus der Liste.

```bash tab="cURL" tab-group="lang"
curl "https://hub.webmetic.de/company-sessions?domain=ihre-website.de&page_size=1" \
  -H "Authorization: wmtc_IHR_API_SCHLUESSEL"
```

```js tab="JavaScript" tab-group="lang"
const res = await fetch(
  'https://hub.webmetic.de/company-sessions?domain=ihre-website.de&page_size=1',
  { headers: { Authorization: 'wmtc_IHR_API_SCHLUESSEL' } },
);
const data = await res.json();
console.log(data.result[0].sessions);
```

```python tab="Python" tab-group="lang"
import requests

res = requests.get(
    "https://hub.webmetic.de/company-sessions",
    params={"domain": "ihre-website.de", "page_size": 1},
    headers={"Authorization": "wmtc_IHR_API_SCHLUESSEL"},
)
data = res.json()
print(data["result"][0]["sessions"])
```

```json title="Antwort (gekürzt)"
{
  "pagination": [
    {
      "total": 32,
      "page_total": 32,
      "isFirst": true,
      "current": 1,
      "isLast": false,
      "page_size": 1
    }
  ],
  "result": [
    {
      "company_id": "41ea486a9c95",
      "company_name": "Bergquell Mineralbrunnen GmbH",
      "company_url": "www.bergquell.example",
      "nace_codes": [
        {
          "code": "11.07",
          "full_code": "C 11.07",
          "description_de": "Herstellung von Erfrischungsgetränken und Mineralwässern",
          "description_en": "Manufacture of soft drinks and bottled waters"
        }
      ],
      "sessions": [
        {
          "session_id": "01M4WQFX6YM2X5V8T4N6R1C0DZ",
          "client_id": "14e382cf709a614559666137b3d1dfcefa99b1e7ecf93400cc9e2cc4822619d3",
          "timestamp": "2026-10-14T08:12:05.214000",
          "weburl": "https://ihre-website.de",
          "session_duration": 309.0,
          "user_data": [
            {
              "timestamp": "2026-10-14T08:12:05.214000",
              "document_location": "https://ihre-website.de/preise",
              "time_spent": 95.0
            }
          ]
        }
      ]
    }
  ]
}
```

Die Reihenfolge der Einträge ist nicht festgelegt. Die meisten Endpunkte lassen ein Feld weg, wenn sein Wert unbekannt ist. Nur die Besuchsarten und `data.visit` in Webhooks liefern jedes Feld und setzen unbekannte Werte auf `null`. Wenn Webmetic eine Zeit nicht messen konnte, steht dort ein geschätzter Wert von wenigen Sekunden, den [Page View](https://webmetic.de/docs/api/datenmodell/page-view) genauer beschreibt.

## Domain in Besuchsdaten und Enrichment [#domain-in-besuchsdaten-und-enrichment]

Der Parameter `domain` hat in der API zwei Bedeutungen:

- **Besuchsdaten**: Ihre Website, deren Besuche Sie abfragen.
- **Enrichment**: das Unternehmen, dessen Daten Sie abrufen.

Die Endpunkte für Ansprechpartner nehmen keine Domain an, nur die `company_id`.

Weil Enrichment-Zeilen keine `company_id` tragen, verbinden Sie die Zeilen über die Domain mit den Besuchsdaten. In den Besuchsdaten kann in `company_url` ein `www.` oder eine andere Subdomain vor der Domain stehen. Kürzen Sie den Wert deshalb vor dem Vergleich auf die Domain, also zum Beispiel `www.bergquell.example` auf `bergquell.example`. [Enrichment-Liste](https://webmetic.de/docs/api/datenmodell/enrichment-liste) beschreibt, wie auch die übrigen Felder in Enrichment anders aussehen.

## Schlüssel, Plan und Credits [#schlüssel-plan-und-credits]

Welche Objekte Sie lesen, hängt vom API-Schlüssel ab, den Sie wie unter [Authentifizierung](https://webmetic.de/docs/api/authentifizierung) beschrieben mitsenden. Admins finden die Schlüssel unter [**Menü** > **Integrationen** > **API**](https://app.webmetic.de/?menu=api_details):

- **Visitor Intelligence**: Unternehmen, Sessions, Seitenaufrufe, Ansprechpartner, Credits und Webhooks.
- **Enrichment**: Enrichment-Listen, ihre Zeilen und die Einzelabfrage. Neue Listen, neue Domains und Einzelabfragen funktionieren nur in der Testphase und in den Plänen Growth und Enterprise.

Im Free-Plan liefert die API auch Unternehmen, die Sie nicht lesen können. Diese Unternehmen tragen nur ihre `company_id`, ihre Sessions mit Zeiten, einen Platzhalter als Namen und `"blurred": true`. Mehr dazu unter [Pläne](https://webmetic.de/docs/konto/plaene).

Nur `/contacts/reveal` und `/contacts/find` kosten Credits. Bevor Sie Ansprechpartner suchen, schließen Sie [Ansprechpartner einrichten](https://webmetic.de/docs/ansprechpartner/einrichten) einmal im Dashboard ab. Sonst antwortet die API mit `CONTACTS_SETUP_REQUIRED`. Enrichment kostet derzeit keine Credits. Mehr dazu unter [Credits in der API](https://webmetic.de/docs/api/credits).

## Nächste Schritte [#nächste-schritte]

- [Company](https://webmetic.de/docs/api/datenmodell/company): Alle Felder eines Unternehmens mit Typ und Beispiel.
- [Session](https://webmetic.de/docs/api/datenmodell/session): Wann ein Besuch beginnt und endet und welche Felder er trägt.
- [Contact](https://webmetic.de/docs/api/datenmodell/contact): Wie ein Ansprechpartner vor und nach dem Freischalten aussieht.