Überblick

HeyLinked API und MCP

Schweizer Firmen und Personen suchen, Kontakte öffnen, Kampagnen steuern und Antworten lesen. Aus dem eigenen Code, aus Cursor, Claude oder ChatGPT, oder aus Make, Zapier und n8n.

Suchen und das Lesen eines gesperrten Profils sind frei. Eine Registerfirma öffnen kostet 5 Credits. Eine Person öffnen kostet 5 Credits für eine hinterlegte E-Mail und 5 für eine Nummer. Ein zweites Öffnen desselben Datensatzes im selben Workspace kostet nichts.

Basisadresse
https://heylinked.io/api/v1
MCP
https://heylinked.io/api/mcp
Header
Authorization: Bearer hr_live_…
Format
JSON
Limit
120 Anfragen pro Minute und Schlüssel

Schnellstart

Zuerst sehen, wer passt. Dann eine Firma lesen. Öffnen, erst wenn sie zählt.

  1. 1

    Schlüssel anlegen

    Einstellungen → API & MCP. Er beginnt mit hr_live_.

  2. 2

    Suchen

    Zum Beispiel IT-Firmen in Zürich mit Website. Kostenlos.

  3. 3

    Lesen

    Die UID aus dem ersten Treffer nehmen. Solange sie gesperrt ist, sehen Sie available, nicht die E-Mail.

  4. 4

    Öffnen

    POST …/unlock. Die Antwort trägt charged, den neuen Stand und das volle Profil.

Drei Aufrufe
# 1  Suchen
curl "https://heylinked.io/api/v1/companies?canton=ZH&industry_branch=it&has_website=yes" \
  -H "Authorization: Bearer hr_live_…"

# 2  Lesen
curl "https://heylinked.io/api/v1/companies/CHE-101.500.085" \
  -H "Authorization: Bearer hr_live_…"

# 3  Öffnen
curl -X POST "https://heylinked.io/api/v1/companies/CHE-101.500.085/unlock" \
  -H "Authorization: Bearer hr_live_…"

Schlüssel

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. Derselbe Schlüssel gilt für REST und MCP.

Authentifizierung

Den Schlüssel auf jede Anfrage an /api/v1 legen, und auf tools/list und tools/call. Fehlende oder widerrufene Schlüssel ergeben 401. Mehr als 120 Anfragen in einer Minute für einen Schlüssel ergeben 429. Antworten sind JSON. Die Endpunkte senden Access-Control-Allow-Origin: *, das ersetzt den Schlüssel nicht.

Rechte

  • read

    Suche, Profile, Listen, gespeicherte Suchen, Kampagnen, Antworten, Signale.

  • unlock

    Öffnet eine Firma oder eine Person. Kostet Credits.

  • campaigns

    Entwürfe, Status, Firmen aufnehmen, Interesse setzen, Webhooks verwalten.

  • signals

    Legt ein Ereignis von aussen an, zum Beispiel aus dem Shop oder dem CRM.

Fehlt das Recht, kommt 403 forbidden_scope.

Header
Authorization: Bearer hr_live_…

MCP verbinden

Der Server spricht Streamable HTTP, zustandslos, JSON-RPC 2.0, unter https://heylinked.io/api/mcp. Ein GET auf die Adresse listet die Werkzeugnamen.

  • Cursor schickt den Schlüssel im Header. Ein Eintrag in den MCP-Einstellungen.

  • Claude und ChatGPT bekommen beim ersten Aufruf ein 401, das auf die OAuth-Daten zeigt. Die Person meldet sich bei HeyLinked an und bestätigt Workspace und Rechte. Kein Schlüssel im Chat.

Das Protokoll ist 2025-03-26. Ein Client, der 2024-11-05 verlangt, bekommt diese Version. text ist ein JSON-String, derselbe Körper wie der passende REST-Aufruf. isError ist true, wenn die Argumente unbrauchbar sind, die UID fehlt oder die Freischaltung kein Guthaben hat.

{
  "mcpServers": {
    "heylinked": {
      "url": "https://heylinked.io/api/mcp",
      "headers": {
        "Authorization": "Bearer hr_live_…"
      }
    }
  }
}
Form eines Werkzeug-Ergebnisses
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{ \"items\": [] }" }],
    "isError": false
  }
}

Werkzeuge

23 Werkzeuge. Jedes braucht das Recht daneben. Die Beschreibung ist der Text, den der Server dem Assistenten liefert.

set_campaign_status mit active, enroll_companies und create_webhook laufen erst, wenn die Argumente confirm: true enthalten. Ein Entwurf verschickt nichts.
  • search_companiesread

    Schweizer Firmen suchen. Liefert Registerdaten, Kurztext, Mitarbeiterband und ob eine Website bekannt ist. Keine E-Mail, kein Telefon, keine Personen. q ist der Anfang des Firmennamens, eine UID oder ein Branchenbegriff. Ort über city, PLZ über postal_code, Kanton über canton. industry_branch ist eine Hauptbranchen-id aus search_options. revenue_band ist eine Schätzung aus dem Mitarbeiterband.

  • get_companyread

    Eine Firma über die UID lesen. Register, Kurztext, Signale und Lage (Vertrauen, Nachfrage, Stellen, BFS). Solange sie gesperrt ist, nur Ja/Nein, ob Website, E-Mail, Telefon oder Personen vorhanden sind. Kontakt, Personen und Insights erst nach unlock_company.

  • unlock_companyunlock

    Registerfirma freischalten. Kostet 5 Credits, ausser die Firma ist in diesem Workspace schon frei. Google Local kostet 15 Credits. Danach das Profil inklusive Registerdaten und hinterlegter Personen dieser Firma.

  • search_peopleread

    Entscheider im Schweizer Bestand suchen. q ist der Anfang des Register-Namens. Rolle über role, Firma über uid. E-Mail, Telefon und LinkedIn bleiben leer; available sagt nur, ob ein Wert hinterlegt ist. Die Werte kommen mit unlock_person. Eine Firmenfreischaltung öffnet das Dossier, nicht automatisch diese Personensuche.

  • get_personread

    Eine Person über ihre id aus search_people lesen. Rolle, Firma und wie viele Personen derselben Firma hinterlegt sind. Kontakt nur, wenn diese Person schon freigeschaltet ist.

  • unlock_personunlock

    Person öffnen. Kein Pauschalpreis. Eine hinterlegte E-Mail kostet 5 Credits, eine hinterlegte Nummer 5. Fehlt der Wert, kostet die Suche danach extra: E-Mail 5, Zentrale 5, Direktnummer 50, Profil 5.

  • list_unlocked_companiesread

    Firmen, die dieser Workspace schon freigeschaltet hat. Kein erneuter Credit. Nützlich, bevor unlock_company noch einmal aufgerufen wird.

  • search_optionsread

    Erlaubte Filterwerte: Kantone, Hauptbranchen mit Unterbranchen, Rechtsformen, Mitarbeiterbänder, Alters-Presets, Herkunft, Sortierung und Credit-Kosten. Vor einer Branchensuche aufrufen, damit die ids stimmen.

  • accountread

    Workspace und Credit-Stand dieses API-Schlüssels. Eine Registerfirma kostet 5 Credits. Personen haben keinen Pauschalpreis.

  • list_campaignsread

    Kampagnen dieses Workspace. Status, Betreff, Zahl der Empfänger und ob schon gesendet, geöffnet oder geantwortet wurde. Kein Versand.

  • get_campaignread

    Eine Kampagne mit Schritten und den ersten 100 Empfängern. Empfänger nur als UID und Status, ohne Mailtext der Person.

  • create_campaigncampaigns

    Legt eine Kampagne als Entwurf an. Es geht keine Mail raus. Der Versand startet erst mit set_campaign_status active und confirm true.

  • set_campaign_statuscampaignsconfirm

    paused oder draft stoppt den Versand. active nimmt ihn wieder auf und braucht confirm true, weil dann das eigene Postfach schreibt.

  • enroll_companiescampaignsconfirm

    Nimmt freigeschaltete Firmen in eine Kampagne auf. Höchstens 25 UID. confirm muss true sein, weil jede neue Firma Empfänger-Credits kostet.

  • list_repliesread

    Die letzten Antworten, Interessensmeldungen, Bounces und Abmeldungen. Optional auf eine Kampagne eingeschränkt.

  • mark_replycampaigns

    Setzt eine Firma in einer Kampagne auf interested oder not_interested. Dafür muss schon eine Mail raus sein. Löst den Webhook aus.

  • list_listsread

    Listen des Workspace mit Anzahl der Einträge. kind ist company oder person.

  • get_listread

    Einträge einer Liste. E-Mail nur, wenn die Firma in diesem Workspace schon freigeschaltet ist.

  • list_saved_searchesread

    Gespeicherte Suchen dieses Workspace, mit dem gespeicherten Filter.

  • list_signalsread

    Die letzten Signale, die diesem Workspace zugeordnet sind. Kein neues Signal, kein Credit.

  • list_webhooksread

    Eingetragene Webhook-URLs und ihre Ereignisse. Das Geheimnis zum Prüfen der Signatur steht hier nicht.

  • create_webhookcampaignsconfirm

    Schickt Ereignisse an eine https-URL. Zapier, Make und n8n empfangen dieselbe Adresse. Ereignisse: reply.received, reply.interested, reply.not_interested, email.bounced, email.unsubscribed. confirm muss true sein. Das Geheimnis kommt nur in dieser Antwort.

  • delete_webhookcampaigns

    Entfernt einen Webhook über seine id aus list_webhooks.

Firmen

Im Handelsregister suchen, ein Profil lesen, Kontakte öffnen.

Firmen suchen

GET/api/v1/companies

Registerdaten, Branche, Kurztext und ob eine Website bekannt ist. Keine E-Mail, kein Telefon, keine Personen. Die Suche ist frei.

Die Werte oben zeigen die Form. Sie sind kein Auszug aus dem Bestand. total ist die Trefferzahl. Seite für Seite weiterblättern, bis items leer ist oder page * page_size die total erreicht.

Parameter

  • qstring

    Anfang des Firmennamens, eine UID, oder ein Branchenbegriff, den die Taxonomie kennt. Kennt HeyLinked den Text als Branche, sucht q die Branche. Sonst den Namensanfang. Der Ort ist city.

  • cantonstring

    Kantonskürzel, zum Beispiel ZH. Ein ausgeschriebener Name ergibt 400.

  • citystring

    Ort, Teilstring.

  • postal_codestring

    Vierstellige PLZ.

  • industry_branchstring

    id einer Hauptbranche aus GET /api/v1/options, zum Beispiel immobilien oder bau.

  • industrystring

    Exaktes Label einer Unterbranche aus derselben Liste. Zusammen mit industry_branch müssen beide passen.

  • legal_formstring

    Zum Beispiel AG oder GmbH.

  • employee_bandstring

    1-10, 11-20, 21-50, 51-100, 101-250, 251+. Schätzung. Steht auch revenue_band, gilt dieses Band.

  • revenue_bandstring

    <0.5M, 0.5-2M, 2-10M, 10-50M, 50M+. Schätzung aus dem Mitarbeiterband, kein gemeldeter Umsatz.

  • founded_fromnumber

    Jahr, inklusive.

  • founded_tonumber

    Jahr, inklusive.

  • company_agestring

    new_7d, new_30d, new_12m, new_24m, new_36m, new_5y, age_10y_plus, age_25y_plus. Schneidet sich mit founded_from und founded_to.

  • has_websitestring

    yes oder no.

  • unlock_statusstring

    unlocked oder locked, bezogen auf diesen Workspace.

  • sourcestring

    zefix (Handelsregister), google_local oder web.

  • sortstring

    name, city, founded, added. Ohne Angabe: founded.

  • pagenumber

    Ab 1. Standard 1.

  • page_sizenumber

    1 bis 50. Standard 25. MCP-Suche standardmässig 15, wenn der Assistent nichts setzt.

curl "https://heylinked.io/api/v1/companies?canton=ZH&industry_branch=it&employee_band=11-20&has_website=yes&founded_from=2018" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "items": [
    {
      "uid": "CHE101500085",
      "uid_formatted": "CHE-101.500.085",
      "name": "Beispiel AG",
      "legal_form": "AG",
      "status": "active",
      "canton": "ZH",
      "city": "Zürich",
      "postal_code": "8001",
      "founded_on": "2014-03-12",
      "industry": "Softwareentwicklung",
      "employee_band": "11-20",
      "revenue_band_estimated": "0.5-2M",
      "unlocked": false,
      "has_website": true,
      "brief": "Seit 2014 in Zürich, geschätzt 11–20 Mitarbeitende."
    }
  ],
  "total": 128,
  "page": 1,
  "page_size": 25
}

Eine Firma lesen

GET/api/v1/companies/{uid}

Profil einer UID: Register, Kurztext, Signale und Lage. Solange die Firma gesperrt ist, sagt available nur, ob Website, E-Mail, Telefon oder Personen vorhanden sind.

Der erste Aufruf einer Firma kann einige Sekunden dauern, weil Suche, Stellen und BFS gelesen und danach zwischengespeichert werden. Leere Felder bleiben leer.

Parameter

  • uidpathPflicht

    Mit oder ohne Formatierung. HeyLinked normalisiert sie. Unbekannt: 404.

curl "https://heylinked.io/api/v1/companies/CHE-101.500.085" \
  -H "Authorization: Bearer hr_live_…"
Beispiel, Firma noch gesperrt
{
  "company": {
    "uid": "CHE101500085",
    "uid_formatted": "CHE-101.500.085",
    "name": "Beispiel AG",
    "legal_name": "Beispiel AG",
    "legal_form": "AG",
    "status": "active",
    "purpose": "Entwicklung von Software.",
    "canton": "ZH",
    "city": "Zürich",
    "postal_code": "8001",
    "street": "Bahnhofstrasse 1",
    "founded_on": "2014-03-12",
    "industry": "Softwareentwicklung",
    "employee_band": "11-20",
    "unlocked": false,
    "brief": "Seit 2014 in Zürich, geschätzt 11–20 Mitarbeitende.",
    "signals": [{ "kind": "age", "text": "Gegründet 2014." }],
    "available": {
      "website": true,
      "email": true,
      "phone": false,
      "people": true
    },
    "lage": {
      "trust": { "score": 0, "label": "" },
      "peers": { "headline": "Einordnung", "detail": "" },
      "image": { "label": "", "detail": "" },
      "demand": {
        "state": "unavailable",
        "verdict": null,
        "label": "",
        "detail": "",
        "change_pct": null,
        "topics": [],
        "lines": [],
        "months": []
      },
      "supply": {
        "group_label": "IT & Software",
        "scope": "",
        "stock": null,
        "supply_change_pct": null,
        "quarters": [],
        "jobs": {
          "state": "unavailable",
          "query": "",
          "total_hits": null,
          "roles": [],
          "detail": ""
        },
        "official": {
          "state": "unavailable",
          "sector_label": "",
          "canton_label": "",
          "years": [],
          "detail": ""
        }
      }
    }
  }
}

Firma freischalten

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

Öffnet die Registerfirma und die Personen dieser Firma. Kostet 5 Credits, ausser die Firma ist in diesem Workspace schon frei. Kein Body.

company ist danach dasselbe volle Profil wie bei GET. Ein zweiter Aufruf setzt charged auf 0 und already_owned auf true. Zu wenig Credits: 402, die Firma bleibt zu. Eine Freischaltung garantiert keine geprüfte E-Mail.

Parameter

  • uidpathPflicht

    Dieselbe UID wie beim Lesen.

curl -X POST "https://heylinked.io/api/v1/companies/CHE-101.500.085/unlock" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "charged": 1,
  "already_owned": false,
  "balance": 9,
  "company": {
    "unlocked": true,
    "contact": {
      "website": "https://beispiel.ch",
      "email": "info@beispiel.ch",
      "phone": null,
      "google_rating": 4.6,
      "google_rating_count": 18
    },
    "people": [
      {
        "name": "Anna Beispiel",
        "role": "Geschäftsführerin",
        "city": "Zürich",
        "email": "anna@beispiel.ch"
      }
    ],
    "insights": {
      "summary": "Kurzfassung der Recherche.",
      "revenue_estimate": "CHF 0.5–2 Mio.",
      "hiring_signal": false,
      "services": ["Software"],
      "outreach_signals": []
    }
  }
}

Personen

Entscheider nach Rolle und Region. Eine Person öffnen ist ein eigener Credit.

Personen suchen

GET/api/v1/people

Entscheider im Register. Name, Rolle und Firma sind sichtbar. E-Mail, Telefon und LinkedIn nicht. available sagt nur, ob ein Wert hinterlegt ist.

total bei Personen ist eine Schätzung der Datenbank, keine exakte Zählung. Die Firmensuche nennt diese Personen nicht. Im geöffneten Firmendossier stehen sie mit, soweit sie zur Firma hinterlegt sind.

Parameter

  • qstring

    Anfang des Register-Namens. «Hans» findet «Hans Meier». «Meier» findet diesen Namen nicht.

  • rolestring

    Teil der Funktion, zum Beispiel Geschäftsführer.

  • cantonstring

    Kantonskürzel.

  • citystring

    Ort, Teilstring.

  • uidstring

    UID der Firma, mit oder ohne Formatierung.

  • sortstring

    added, name, city, company. Ohne Angabe: added.

  • pagenumber

    Ab 1.

  • page_sizenumber

    1 bis 50. Standard 25.

curl "https://heylinked.io/api/v1/people?role=Geschäftsführer&canton=BE" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "items": [
    {
      "id": "8f1c…",
      "uid": "CHE101500085",
      "name": "Anna Beispiel",
      "role": "Geschäftsführerin",
      "city": "Bern",
      "canton": "BE",
      "company": {
        "uid": "CHE101500085",
        "name": "Beispiel AG",
        "legal_form": "AG",
        "city": "Bern",
        "canton": "BE",
        "industry": "Softwareentwicklung"
      },
      "unlocked": false,
      "available": { "email": true, "phone": false, "linkedin": true }
    }
  ],
  "total": 40,
  "page": 1,
  "page_size": 25
}

Eine Person lesen

GET/api/v1/people/{id}

Eine Person über die id aus der Personensuche. colleagues ist die Zahl der hinterlegten Personen derselben Firma, inklusive dieser.

Parameter

  • idpathPflicht

    Die id aus der Personensuche, nicht die UID der Firma.

curl "https://heylinked.io/api/v1/people/8f1c…" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "person": {
    "id": "8f1c…",
    "name": "Anna Beispiel",
    "role": "Geschäftsführerin",
    "unlocked": false,
    "available": { "email": true, "phone": false, "linkedin": true },
    "colleagues": 3,
    "company": { "uid": "CHE101500085", "name": "Beispiel AG" }
  }
}

Person freischalten

POST/api/v1/people/{id}/unlock

Öffnet die Person. Kein Pauschalpreis. Eine hinterlegte E-Mail kostet 5 Credits, eine Nummer 5. Das ist getrennt von der Registerfirma. Kein Body.

Fehlt die Adresse, ist das Feld null. Ein zweiter Aufruf berechnet nichts noch einmal.

Parameter

  • idpathPflicht

    Personen-id.

curl -X POST "https://heylinked.io/api/v1/people/8f1c…/unlock" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "charged": 1,
  "already_owned": false,
  "balance": 8,
  "person": {
    "id": "8f1c…",
    "unlocked": true,
    "contact": {
      "email": "anna@beispiel.ch",
      "email_status": "found",
      "phone": null,
      "linkedin_url": "https://www.linkedin.com/in/beispiel"
    }
  }
}

Konto

Was schon offen ist, welche Filterwerte es gibt, und der Kontostand.

Schon geöffnete Firmen

GET/api/v1/unlocks

Firmen, die dieser Workspace schon freigeschaltet hat. Kein weiterer Credit. Nützlich, bevor ein Ablauf noch einmal öffnet.

Parameter

  • pagenumber

    Ab 1.

  • page_sizenumber

    1 bis 50. Standard 25.

curl "https://heylinked.io/api/v1/unlocks?page=1&page_size=25" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "items": [
    {
      "uid": "CHE101500085",
      "uid_formatted": "CHE-101.500.085",
      "name": "Beispiel AG",
      "legal_form": "AG",
      "canton": "ZH",
      "city": "Zürich",
      "postal_code": "8001",
      "industry": "Softwareentwicklung",
      "unlocked_at": "2026-11-16T18:00:00.000Z",
      "credits_charged": 1,
      "enrichment_status": "ready",
      "last_enriched_at": "2026-11-16T18:00:04.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 25
}

Filterwerte

GET/api/v1/options

Die Werte, die die Suche wirklich versteht. Vor einer Branchensuche aufrufen, damit industry_branch eine id ist und industry ein Label.

Die Liste oben ist gekürzt. Die echte Antwort enthält alle Kantone, Hauptbranchen und Unterbranchen.

Keine Parameter.

curl "https://heylinked.io/api/v1/options" \
  -H "Authorization: Bearer hr_live_…"
Form der Antwort
{
  "cantons": ["AG", "ZH"],
  "industries": [
    { "id": "it", "label": "IT & Software", "subindustries": ["Softwareentwicklung"] }
  ],
  "legal_forms": ["AG", "GmbH"],
  "employee_bands": ["1-10", "11-20"],
  "revenue_bands": [{ "id": "0.5-2M", "label": "CHF 0.5–2 Mio." }],
  "company_age": [{ "id": "new_12m", "label": "Neugründung · letztes Jahr" }],
  "sources": [{ "id": "zefix", "label": "Handelsregister" }],
  "company_sorts": ["name", "city", "founded", "added"],
  "people_sorts": ["added", "name", "city", "company"],
  "costs": { "company_unlock": 5, "google_local": 15, "person_unlock": 0, "email_find": 5, "phone_main": 5, "phone_direct": 50 },
  "notes": { "q": "Anfang des Firmennamens, eine UID, oder ein Branchenbegriff." }
}

Konto

GET/api/v1/me

Workspace, Credit-Stand und was eine Freischaltung kostet.

Keine Parameter.

curl "https://heylinked.io/api/v1/me" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "workspace_id": "ws_…",
  "balance": 10,
  "unlock_credit_cost": 5,
  "google_local_credit_cost": 15,
  "person_unlock_credit_cost": 0,
  "email_find_credit_cost": 5,
  "phone_direct_credit_cost": 50
}

Kampagnen

Kampagnen lesen, Entwürfe anlegen, Versand anhalten und starten, Firmen aufnehmen. Zum Schreiben braucht es das Recht campaigns.

Kampagnen lesen

GET/api/v1/campaigns

Kampagnen dieses Workspace. Status, Betreff, Empfängerzahl und ob schon gesendet, geöffnet oder geantwortet wurde. Kein Versand. Recht: read.

Keine Parameter.

curl "https://heylinked.io/api/v1/campaigns" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "campaigns": [
    {
      "id": "cmp_…",
      "name": "Architekten Zürich",
      "status": "paused",
      "subject": "Kurz zu Ihrer Pipeline",
      "recipient_count": 12,
      "sent": 12,
      "opened": 4,
      "replied": 1
    }
  ]
}

Kampagne anlegen

POST/api/v1/campaigns

Legt einen Entwurf an. Es geht keine Mail raus. Recht: campaigns.

Parameter

  • namestringPflicht

    2 bis 80 Zeichen.

  • subjectstring

    Betreff des ersten Schritts.

  • bodystring

    Text des ersten Schritts.

curl -X POST "https://heylinked.io/api/v1/campaigns" \
  -H "Authorization: Bearer hr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Architekten Zürich","subject":"Kurz zu Ihrer Pipeline","body":"…"}'
Beispielantwort, Status 201
{ "campaign": { "id": "cmp_…", "name": "Architekten Zürich", "status": "draft" } }

Eine Kampagne

GET/api/v1/campaigns/{id}

Schritte und die ersten 100 Empfänger. Empfänger nur als UID und Status, ohne den Mailtext der Person. Recht: read.

Parameter

  • idstringPflicht

    In der Pfadangabe.

curl "https://heylinked.io/api/v1/campaigns/cmp_…" \
  -H "Authorization: Bearer hr_live_…"
Form der Antwort
{
  "campaign": { "id": "cmp_…", "name": "Architekten Zürich", "status": "draft", "subject": "…" },
  "steps": [{ "position": 1, "delay_days": 0, "subject": "…", "body": "…" }],
  "recipients": [{ "uid": "CHE-101.500.085", "status": "queued", "current_step": 1 }],
  "recipient_total": 1,
  "recipients_truncated": false
}

Versand anhalten oder starten

POST/api/v1/campaigns/{id}/status

paused und draft stoppen den Versand. active nimmt ihn wieder auf und braucht confirm true, weil dann das eigene Postfach schreibt. Recht: campaigns.

Parameter

  • statusstringPflicht

    paused, draft oder active.

  • confirmbooleanbei active

    Muss true sein, sonst 400 confirmation_required.

curl -X POST "https://heylinked.io/api/v1/campaigns/cmp_…/status" \
  -H "Authorization: Bearer hr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"active","confirm":true}'
Beispielantwort
{ "campaign": { "id": "cmp_…", "name": "Architekten Zürich", "status": "active" } }

Firmen aufnehmen

POST/api/v1/campaigns/{id}/recipients

Nimmt schon freigeschaltete Firmen auf. Höchstens 25 UID. confirm muss true sein, weil jede neue Firma Empfänger-Credits kostet. Recht: campaigns.

Parameter

  • uidsstring[]Pflicht

    1 bis 25 UID.

  • confirmbooleanPflicht

    Muss true sein.

curl -X POST "https://heylinked.io/api/v1/campaigns/cmp_…/recipients" \
  -H "Authorization: Bearer hr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"uids":["CHE-101.500.085"],"confirm":true}'
Beispielantwort
{
  "enrolled": [{ "uid": "CHE-101.500.085", "status": "queued" }],
  "errors": [],
  "charged": 1
}

Antworten

Antworten, Interesse, Bounces und Abmeldungen über alle Kampagnen.

Antworten lesen

GET/api/v1/replies

Die letzten Antworten, Interessensmeldungen, Bounces und Abmeldungen. Optional auf eine Kampagne eingeschränkt. Recht: read.

Parameter

  • campaign_idstring

    Ohne Angabe: alle Kampagnen des Workspace.

curl "https://heylinked.io/api/v1/replies?campaign_id=cmp_…" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "replies": [
    {
      "kind": "replied",
      "campaign_id": "cmp_…",
      "campaign_name": "Architekten Zürich",
      "company_uid": "CHE-101.500.085",
      "email": "a@firma.ch",
      "created_at": "2026-11-19T08:00:00.000Z"
    }
  ]
}

Interesse setzen

POST/api/v1/replies

Setzt eine Firma auf interested oder not_interested. Dafür muss schon eine Mail raus sein. Löst denselben Webhook aus wie eine Markierung in der Oberfläche. Recht: campaigns.

Parameter

  • campaign_idstringPflicht

    Kampagne, in der die Firma liegt.

  • uidstringPflicht

    Firma in dieser Kampagne.

  • kindstringPflicht

    interested oder not_interested.

curl -X POST "https://heylinked.io/api/v1/replies" \
  -H "Authorization: Bearer hr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":"cmp_…","uid":"CHE-101.500.085","kind":"interested"}'
Beispielantwort
{ "ok": true, "campaign_id": "cmp_…", "uid": "CHE-101.500.085", "kind": "interested" }

Listen und Signale

Listen und gespeicherte Suchen aus dem Workspace. Signale von aussen, zum Beispiel eine gebuchte Demo.

Listen

GET/api/v1/lists

Listen des Workspace. kind filtert auf company oder person. Die Einträge einer Liste stehen unter /api/v1/lists/{id}. Eine E-Mail steht dort nur, wenn die Firma schon freigeschaltet ist. Recht: read.

Parameter

  • kindstring

    company oder person.

curl "https://heylinked.io/api/v1/lists?kind=company" \
  -H "Authorization: Bearer hr_live_…"
Beispielantwort
{
  "lists": [
    { "id": "lst_…", "name": "Zürich IT", "kind": "company", "item_count": 18 }
  ]
}

Gespeicherte Suchen

GET/api/v1/saved-searches

Gespeicherte Suchen mit dem gespeicherten Filter. Recht: read.

Keine Parameter.

curl "https://heylinked.io/api/v1/saved-searches" \
  -H "Authorization: Bearer hr_live_…"
Form der Antwort
{ "searches": [{ "id": "ss_…", "name": "IT Zürich", "query": { "canton": "ZH" } }] }

Signale lesen

GET/api/v1/signals

Die letzten Signale, die diesem Workspace zugeordnet sind. Kostet keinen Credit. Recht: read.

Keine Parameter.

curl "https://heylinked.io/api/v1/signals" \
  -H "Authorization: Bearer hr_live_…"
Form der Antwort
{
  "signals": [
    { "id": "sig_…", "kind": "external", "company_uid": "CHE-101.500.085", "title": "Demo gebucht" }
  ]
}

Signal anlegen

POST/api/v1/signals

Ihr Shop, Ihre Website oder Ihr CRM meldet ein Ereignis an eine Firma. Kostet keinen Credit. Eine unbekannte UID wird abgelehnt. Dieselbe idempotency_key legt das Signal nur einmal an. Recht: signals.

Kommt dieselbe idempotency_key noch einmal, ist duplicate true und der Status 200. Der Aufruf bleibt kostenlos.

Parameter

  • titlestringPflicht

    3 bis 240 Zeichen.

  • company_uidstringoder company_name

    UID aus dem Bestand.

  • company_namestringoder company_uid

    Wird einer bekannten Firma zugeordnet, wenn keine UID mitkommt.

  • idempotency_keystring

    Dieselbe Firma und derselbe Schlüssel nur einmal.

curl -X POST "https://heylinked.io/api/v1/signals" \
  -H "Authorization: Bearer hr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Demo gebucht","company_uid":"CHE-101.500.085","idempotency_key":"shop-42"}'
Beispielantwort, Status 201
{ "ok": true, "duplicate": false, "company_uid": "CHE-101.500.085" }

Webhooks

Eine HTTPS-Adresse empfängt Antworten, Interesse, Bounces und Abmeldungen. Zapier (Webhooks by Zapier), Make (HTTP) und n8n nutzen dieselbe Adresse. Dafür entsteht keine App bei denen. Anlegen unter Einstellungen → API, oder mit POST /api/v1/webhooks und dem Recht campaigns. Das Geheimnis kommt beim Anlegen zurück und bleibt für Admins sichtbar.

Ereignisse

  • reply.received
  • reply.interested
  • reply.not_interested
  • email.bounced
  • email.unsubscribed

Signatur prüfen

X-HeyLinked-Signature ist HMAC-SHA256 mit dem Geheimnis über {timestamp}.{Rohtext}. Vergleichen, bevor Sie dem Inhalt trauen. Ohne events-Liste beim Anlegen gelten alle Ereignisse.

cURL
curl -X POST "https://heylinked.io/api/v1/webhooks" \
  -H "Authorization: Bearer hr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hook.eu1.make.com/…","events":["reply.received","reply.interested"]}'
Zustellung
X-HeyLinked-Event: reply.received
X-HeyLinked-Delivery: 2b6f…
X-HeyLinked-Timestamp: 1732000000
X-HeyLinked-Signature: sha256=…

{
  "id": "2b6f…",
  "event": "reply.received",
  "created_at": "2026-11-19T09:12:00.000Z",
  "workspace_id": "ws_…",
  "campaign": { "id": "cmp_…", "name": "Architekten Zürich" },
  "company_uid": "CHE-101.500.085",
  "recipient_id": "rcp_…",
  "email": "info@…",
  "step_position": 1
}

Felder

Ein Suchtreffer ist die kurze Zeile. Ein Firmenprofil ergänzt Registertext, Signale und die Lage. Kontakt, Personen und Insights kommen erst nach der Firmenfreischaltung. Eine Person aus der Personensuche bleibt zu, bis diese Person freigeschaltet ist.

Suchtreffer

  • uidstringPflicht

    Schlüssel im Bestand.

  • uid_formattedstringPflicht

    Lesbare UID.

  • namestringPflicht

    Firmenname.

  • legal_formstringPflicht

    Rechtsform.

  • statusstringPflicht

    active oder ein anderer Registerstatus.

  • cantonstringPflicht

    Kantonskürzel.

  • citystringPflicht

    Ort.

  • postal_codestringPflicht

    PLZ.

  • founded_onstring | nullPflicht

    ISO-Datum, wenn bekannt.

  • industrystringPflicht

    Hinterlegte Branche.

  • employee_bandstringPflicht

    Geschätztes Band, kann leer sein.

  • revenue_band_estimatedstring | nullPflicht

    Aus dem Mitarbeiterband geschätzt.

  • unlockedbooleanPflicht

    Ob dieser Workspace die Firma schon geöffnet hat.

  • has_websitebooleanPflicht

    Ob eine eigene Website bekannt ist. Die Adresse steht hier nicht.

  • briefstringPflicht

    Ein Satz aus Gründung, Grösse und Zweck.

Firmenprofil, über den Treffer hinaus

  • purposestringPflicht

    Zweck aus dem Register, wenn vorhanden.

  • streetstringPflicht

    Strasse.

  • legal_namestringPflicht

    Eingetragener Name.

  • signalsarrayPflicht

    Kurze Fakten. kind ist web, hiring, demand, age oder purpose.

  • availableobjectnur solange gesperrt

    website, email, phone, people als Ja/Nein. Keine Werte.

  • contactobjectnur nach Freischaltung

    website, email, phone, google_rating, google_rating_count.

  • peoplearraynur nach Freischaltung

    name, role, city, und soweit vorhanden email, phone, linkedin_url.

  • insightsobjectnur nach Freischaltung

    summary, revenue_estimate, hiring_signal, services, outreach_signals.

  • lage.trustobjectPflicht

    score und label. Wie belastbar die Einordnung ist.

  • lage.peersobjectPflicht

    headline und detail. Einordnung zur Branche.

  • lage.imageobjectPflicht

    label und detail zum öffentlichen Bild.

  • lage.demandobjectPflicht

    Suchkurve: state, verdict, label, detail, change_pct, topics, lines, months.

  • lage.supplyobjectPflicht

    Neugründungen der Branche, Stellenrollen und die BFS-Reihe des Sektors. Das beschreibt den Sektor, nicht immer die einzelne Firma.

Person

  • idstringPflicht

    Für GET und POST /people/{id}.

  • rolestring | nullPflicht

    Funktion im Register.

  • companyobjectPflicht

    uid, name, legal_form, city, canton, industry.

  • availableobjectnur solange gesperrt

    email, phone, linkedin als Ja/Nein.

  • contactobjectnur nach Freischaltung

    email, email_status, phone, linkedin_url. Leer heisst: nicht hinterlegt.

  • colleaguesnumbernur bei GET einer Person

    Personen derselben Firma, inklusive dieser.

Fehler

Der HTTP-Status passt zum Fall. code bleibt stabil, message ist für Menschen.

  • 401
    unauthorized

    Schlüssel fehlt, ist falsch oder widerrufen.

  • 400
    bad_request

    Parameter unbrauchbar. message sagt, welches Feld.

  • 404
    not_found

    UID oder Person nicht im Bestand.

  • 402
    insufficient_credits

    Freischaltung ohne Guthaben. Nichts wurde geöffnet.

  • 400
    confirmation_required

    active, das Aufnehmen von Firmen oder ein Webhook aus dem Assistenten ohne confirm true.

  • 403
    forbidden_scope

    Der Schlüssel hat das Recht nicht: read, unlock, campaigns oder signals.

  • 429
    rate_limited

    Mehr als 120 Anfragen in einer Minute für diesen Schlüssel.

  • 500
    error

    Die Anfrage ist fehlgeschlagen.

Die Mitarbeiterzahl ist eine Schätzung. Stellenrollen und die BFS-Zeile beschreiben die Branche und den Sektor, nicht immer die einzelne Firma. Eine Freischaltung verspricht keine geprüfte Adresse.

Fehlerkörper
{
  "error": {
    "code": "bad_request",
    "message": "canton ist ein Kantonskürzel, zum Beispiel ZH, BE oder GE."
  }
}

Fragen

Wie erhalte ich einen API-Schlüssel?

Im Workspace unter Einstellungen → API & MCP. Der Schlüssel wird nur einmal vollständig angezeigt und kann jederzeit widerrufen werden. Pro Workspace sind 10 aktive Schlüssel möglich.

Kann ich zuerst nur suchen?

Ja. Suchen und das Lesen eines gesperrten Profils sind frei. Das Dossier öffnen Sie erst, wenn die Firma zählt. Eine Person zu öffnen ist ein eigener Credit.

Was ist der Unterschied zwischen API und MCP?

Die REST-API ist für eigene Programme. MCP stellt dieselben Aufrufe als Werkzeuge bereit. Cursor nutzt den API-Schlüssel. Claude und ChatGPT melden die Person per OAuth an. Suche, Listen, Kampagnen und Antworten sind dieselben.

Gibt es ein Rate Limit?

Ja. Pro API-Schlüssel sind höchstens 120 Anfragen pro Minute möglich. Danach antwortet die API mit 429.

Ist die Trefferzahl bei Personen exakt?

Bei Firmen ist total die Trefferzahl. Bei Personen ist total eine Schätzung der Datenbank. Die Zeilen auf der Seite sind die echten Treffer.

Kann ich HeyLinked mit meinem CRM verbinden?

Ja, über eine Adresse. HeyLinked schickt Antworten, Interesse, Bounces und Abmeldungen an Make, Zapier oder n8n. Das Szenario schreibt dann nach HubSpot, Pipedrive oder Salesforce. Eine App in diesen Systemen gibt es dafür nicht.

Kann ein Assistent eine Kampagne starten?

Er kann suchen, Listen und Kampagnen lesen und einen Entwurf anlegen. Pausieren stoppt den Versand. Wieder starten und Firmen aufnehmen gehen nur mit confirm true, damit nicht unbegrenzt Credits oder Mails ausgelöst werden.