---
title: "Bis zu 500 Firmen ohne bekannte UID sicher zuordnen"
method: POST
path: "/companies/match"
tags: ["Firmen"]
---

# Bis zu 500 Firmen ohne bekannte UID sicher zuordnen

`POST /companies/match`

## Request

- Base URL: `https://firmenwatch.ch/api/v1`
- URL: `https://firmenwatch.ch/api/v1/companies/match`
- Auth: HTTP bearer

Vorabgleich fuer ERP-/CRM-Bestaende, in denen die Schweizer UID noch fehlt. Der locker normalisierte aktuelle Firmenname findet Kandidaten; automatisch matched wird ausschliesslich ein streng gleicher vollstaendiger Name zusammen mit passender PLZ oder passendem Ort und ohne widersprechende Ortsangabe. Mehrdeutige Zeilen bleiben pruefpflichtig. Reihenfolge, Dubletten und external_ref bleiben erhalten. Danach bestaetigte UIDs ueber /companies/reconcile mit dem Ereignisstrom verbinden.

## Request body

- object
  - `items` CompanyMatchInput[], required
    - `name` string: Aktueller vollstaendiger Firmenname. Fehlende oder zu kurze Namen werden zeilenweise invalid.
    - `zip` string, nullable: Postleitzahl des Domizils; starkes Zuordnungssignal.
    - `town` string, nullable: Postalischer Ort des Domizils; starkes Zuordnungssignal.
    - `canton` string, nullable: Schweizer Kantonskuerzel; zusaetzliches Kontrollsignal.
    - `external_ref` string, nullable: Eigener unveraenderter Zuordnungsschluessel, zum Beispiel eine Brokanto- oder CRM-ID.

## Response `200`

Zeilengenaue, erklaerbare Zuordnung; nur status=matched darf automatisch uebernommen werden.

- object
  - `data` object, required
    - `matcher` CompanyMatcher, required
      - `version` 'company-match/1.0', required
      - `name_scope` 'current_only', required: Version 1 gleicht aktuelle Registerfirmennamen ab, keine historischen Namen.
      - `automatic_rule` 'strict_current_name_plus_zip_or_town', required
    - `items` CompanyMatchResult[], required
      - `input_index` integer, required: Nullbasierte Position der Eingabe; Reihenfolge und Dubletten bleiben erhalten.
      - `input` object, required
        - `name` string, required
        - `zip` string, nullable, required
        - `town` string, nullable, required
        - `canton` string, nullable, required
        - `external_ref` string, nullable, required
      - `normalized_name` string, nullable, required
      - `status` 'matched' | 'ambiguous' | 'not_found' | 'invalid', required
      - `reason` 'unique_strict_name_and_location' | 'location_disambiguated' | 'candidate_set_incomplete' | 'multiple_strict_names' | 'normalized_name_only' | 'location_mismatch' | 'location_unconfirmed' | 'no_normalized_name' | 'missing_name' | 'name_too_short' | 'invalid_canton', required
      - `message` string, required
      - `company` CompanyMatchCompany, required
        - `uid` string, required
        - `name` string, required
        - `status` 'active' | 'in_liquidation' | 'bankrupt' | 'deleted', required
        - `legal_form_code` string, nullable, required
        - `legal_form` string, nullable, required
        - `address` object, required
          - `zip` string, nullable, required
          - `town` string, nullable, required
          - `canton` string, nullable, required
        - `url` string, uri, required
        - `match` CompanyMatchSignals, required
          - `name` 'strict_exact' | 'normalized_exact', required: strict_exact behaelt Rechtsform und bedeutungstragende Namensbestandteile.
          - `zip` 'match' | 'mismatch' | 'unknown' | 'not_provided', required
          - `town` 'match' | 'mismatch' | 'unknown' | 'not_provided', required
          - `canton` 'match' | 'mismatch' | 'unknown' | 'not_provided', required
      - `candidates` CompanyMatchCompany[], required
        - `uid` string, required
        - `name` string, required
        - `status` 'active' | 'in_liquidation' | 'bankrupt' | 'deleted', required
        - `legal_form_code` string, nullable, required
        - `legal_form` string, nullable, required
        - `address` object, required
          - `zip` string, nullable, required
          - `town` string, nullable, required
          - `canton` string, nullable, required
        - `url` string, uri, required
        - `match` CompanyMatchSignals, required
          - `name` 'strict_exact' | 'normalized_exact', required: strict_exact behaelt Rechtsform und bedeutungstragende Namensbestandteile.
          - `zip` 'match' | 'mismatch' | 'unknown' | 'not_provided', required
          - `town` 'match' | 'mismatch' | 'unknown' | 'not_provided', required
          - `canton` 'match' | 'mismatch' | 'unknown' | 'not_provided', required
    - `summary` CompanyMatchSummary, required
      - `received` integer, required
      - `matched` integer, required
      - `ambiguous` integer, required
      - `not_found` integer, required
      - `invalid` integer, required

## Other responses

- `400`: Ungueltige Anfrage (invalid_request).
- `401`: Kein oder ungueltiger Schluessel (unauthorized).
- `402`: Monatskontingent erschoepft (quota_exceeded).
- `403`: Abonnement nicht aktiv oder benoetigtes Schluesselrecht fehlt (forbidden).
- `429`: Ratenbegrenzung erreicht (rate_limited).
- `500`: Unerwarteter Fehler (internal).
- `503`: Ein amtlicher Publikationsabgleich ist offen; denselben Stapel nach Retry-After erneut senden.

---

[API](https://skmtc.dev/firmenwatch/apis/firmenwatch-api.md) · [All operations](https://skmtc.dev/firmenwatch/apis/firmenwatch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/firmenwatch/apis/firmenwatch-api/revisions/65e774135677?raw)