Schnittstellen für Schweizer Firmendaten

Ein Workspace bekommt einen Schlüssel. Jede Anfrage trägt ihn im Header. Die Basisadresse ist https://heyreach.ch. Lokal gelten dieselben Pfade auf dem laufenden Server.

Die Suche liefert Registerdaten, Branche, den Kurztext und ob eine Website bekannt ist. Sie liefert keine E-Mail, kein Telefon und keine Personen. Dafür gibt es POST …/unlock. Das kostet 1 Credit, ausser die Firma ist in diesem Workspace schon frei. Ein zweiter Aufruf berechnet nichts noch einmal.

MCP ist dieselbe Schnittstelle für Assistenten. Cursor oder ein eigener Agent sieht vier Werkzeuge: suchen, lesen, freischalten, Kontostand. Freischalten zieht denselben Credit.

Unter Einstellungen → API & MCP einen Namen vergeben und den Schlüssel anlegen. Er beginnt mit hr_live_ und wird nur dieses eine Mal angezeigt. Gespeichert wird der Hash. Widerruf gilt sofort. Pro Workspace sind 10 aktive Schlüssel möglich.

Jede Anfrage an /api/v1 und die Werkzeuge von /api/mcp:

Authorization: Bearer hr_live_…

Höchstens 120 Anfragen pro Minute und Schlüssel.

GET /api/v1/companies

curl "https://heyreach.ch/api/v1/companies?q=Abegg&canton=ZH" \
  -H "Authorization: Bearer hr_live_…"

Parameter, alle optional:

• q Name, Zweck oder Ort
• canton Kürzel, zum Beispiel ZH
• city
• industry exakte Branche, zum Beispiel Immobilien
• employee_band 1-10, 11-20, 21-50, 51-100, 101-250, 251+
• has_website yes oder no
• founded_from und founded_to als Jahr
• page ab 1, page_size höchstens 50

Die Antwort enthält items, total, page und page_size. Jeder Treffer hat UID, Name, Sitz, Branche, Gründung, Mitarbeiterband als Schätzung, unlocked, has_website und brief.

GET /api/v1/companies/{uid}

curl "https://heyreach.ch/api/v1/companies/CHE-101.500.085" \
  -H "Authorization: Bearer hr_live_…"

Die UID darf mit oder ohne Formatierung ankommen, HeyReach normalisiert sie. Die Antwort hat company mit Register, Kurztext, Signalen (Website, Stellen, Alter, Suchkurve) und der Lage: Vertrauen, Einordnung, Suchkurve, Neugründungen, Stellenrollen der Branche und die BFS-Reihe des Sektors.

Solange die Firma gesperrt ist, stehen unter available nur Ja/Nein-Felder, ob Website, E-Mail, Telefon oder Personen vorhanden sind. Nach der Freischaltung kommen contact, people und insights. Der erste Aufruf einer Firma kann einige Sekunden dauern, weil Suche, Stellen und BFS gelesen und danach zwischengespeichert werden.

POST /api/v1/companies/{uid}/unlock

curl -X POST "https://heyreach.ch/api/v1/companies/CHE-101.500.085/unlock" \
  -H "Authorization: Bearer hr_live_…"

Antwort: charged ist 1 oder 0, already_owned, der neue balance und company als volles Profil. Bei zu wenig Credits kommt Status 402.

GET /api/v1/me liefert workspace_id, balance und unlock_credit_cost.

curl "https://heyreach.ch/api/v1/me" \
  -H "Authorization: Bearer hr_live_…"

Der Server spricht Streamable HTTP, zustandslos, JSON-RPC 2.0. Adresse: https://heyreach.ch/api/mcp

In Cursor einen MCP-Server mit dieser URL und dem Header eintragen:

{
  "mcpServers": {
    "heyreach": {
      "url": "https://heyreach.ch/api/mcp",
      "headers": {
        "Authorization": "Bearer hr_live_…"
      }
    }
  }
}

Werkzeuge:

• search_companies mit q, canton, city, industry, has_website, page
• get_company mit uid
• unlock_company mit uid, kostet 1 Credit
• account für den Credit-Stand

initialize und ping brauchen keinen Schlüssel. tools/list und tools/call schon. Ein GET auf die Adresse zeigt nur den Hinweis, dass der Aufruf per POST kommt.

Fehler haben die Form { "error": { "code", "message" } }.

• 401 unauthorized Schlüssel fehlt, ist falsch oder widerrufen
• 404 not_found UID nicht im Bestand
• 402 insufficient_credits Freischaltung ohne Guthaben
• 400 bad_request Parameter unbrauchbar
• 429 rate_limited mehr als 120 Anfragen in einer Minute

Die Mitarbeiterzahl ist eine Schätzung. Stellenrollen und die BFS-Zeile beschreiben die Branche und den Sektor, nicht die einzelne Firma. Löschungen über die Zeit liegen nicht als Serie vor.