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
Schlüssel anlegen
Einstellungen → API & MCP. Er beginnt mit hr_live_.
- 2
Suchen
Zum Beispiel IT-Firmen in Zürich mit Website. Kostenlos.
- 3
Lesen
Die UID aus dem ersten Treffer nehmen. Solange sie gesperrt ist, sehen Sie available, nicht die E-Mail.
- 4
Öffnen
POST …/unlock. Die Antwort trägt charged, den neuen Stand und das volle Profil.
# 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
readSuche, Profile, Listen, gespeicherte Suchen, Kampagnen, Antworten, Signale.
unlockÖffnet eine Firma oder eine Person. Kostet Credits.
campaignsEntwürfe, Status, Firmen aufnehmen, Interesse setzen, Webhooks verwalten.
signalsLegt ein Ereignis von aussen an, zum Beispiel aus dem Shop oder dem CRM.
Fehlt das Recht, kommt 403 forbidden_scope.
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_…"
}
}
}
}{
"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_companiesreadSchweizer 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_companyreadEine 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_companyunlockRegisterfirma 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_peoplereadEntscheider 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_personreadEine 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_personunlockPerson ö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_companiesreadFirmen, die dieser Workspace schon freigeschaltet hat. Kein erneuter Credit. Nützlich, bevor unlock_company noch einmal aufgerufen wird.
search_optionsreadErlaubte Filterwerte: Kantone, Hauptbranchen mit Unterbranchen, Rechtsformen, Mitarbeiterbänder, Alters-Presets, Herkunft, Sortierung und Credit-Kosten. Vor einer Branchensuche aufrufen, damit die ids stimmen.
accountreadWorkspace und Credit-Stand dieses API-Schlüssels. Eine Registerfirma kostet 5 Credits. Personen haben keinen Pauschalpreis.
list_campaignsreadKampagnen dieses Workspace. Status, Betreff, Zahl der Empfänger und ob schon gesendet, geöffnet oder geantwortet wurde. Kein Versand.
get_campaignreadEine Kampagne mit Schritten und den ersten 100 Empfängern. Empfänger nur als UID und Status, ohne Mailtext der Person.
create_campaigncampaignsLegt eine Kampagne als Entwurf an. Es geht keine Mail raus. Der Versand startet erst mit set_campaign_status active und confirm true.
set_campaign_statuscampaignsconfirmpaused oder draft stoppt den Versand. active nimmt ihn wieder auf und braucht confirm true, weil dann das eigene Postfach schreibt.
enroll_companiescampaignsconfirmNimmt freigeschaltete Firmen in eine Kampagne auf. Höchstens 25 UID. confirm muss true sein, weil jede neue Firma Empfänger-Credits kostet.
list_repliesreadDie letzten Antworten, Interessensmeldungen, Bounces und Abmeldungen. Optional auf eine Kampagne eingeschränkt.
mark_replycampaignsSetzt eine Firma in einer Kampagne auf interested oder not_interested. Dafür muss schon eine Mail raus sein. Löst den Webhook aus.
list_listsreadListen des Workspace mit Anzahl der Einträge. kind ist company oder person.
get_listreadEinträge einer Liste. E-Mail nur, wenn die Firma in diesem Workspace schon freigeschaltet ist.
list_saved_searchesreadGespeicherte Suchen dieses Workspace, mit dem gespeicherten Filter.
list_signalsreadDie letzten Signale, die diesem Workspace zugeordnet sind. Kein neues Signal, kein Credit.
list_webhooksreadEingetragene Webhook-URLs und ihre Ereignisse. Das Geheimnis zum Prüfen der Signatur steht hier nicht.
create_webhookcampaignsconfirmSchickt 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_webhookcampaignsEntfernt einen Webhook über seine id aus list_webhooks.
Firmen
Firmen suchen
Registerdaten, Branche, Kurztext und ob eine Website bekannt ist. Keine E-Mail, kein Telefon, keine Personen. Die Suche ist frei.
Parameter
qstringAnfang 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.
cantonstringKantonskürzel, zum Beispiel ZH. Ein ausgeschriebener Name ergibt 400.
citystringOrt, Teilstring.
postal_codestringVierstellige PLZ.
industry_branchstringid einer Hauptbranche aus GET /api/v1/options, zum Beispiel immobilien oder bau.
industrystringExaktes Label einer Unterbranche aus derselben Liste. Zusammen mit industry_branch müssen beide passen.
legal_formstringZum Beispiel AG oder GmbH.
employee_bandstring1-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_fromnumberJahr, inklusive.
founded_tonumberJahr, inklusive.
company_agestringnew_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_websitestringyes oder no.
unlock_statusstringunlocked oder locked, bezogen auf diesen Workspace.
sourcestringzefix (Handelsregister), google_local oder web.
sortstringname, city, founded, added. Ohne Angabe: founded.
pagenumberAb 1. Standard 1.
page_sizenumber1 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_…"{
"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
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.
Parameter
uidpathPflichtMit oder ohne Formatierung. HeyLinked normalisiert sie. Unbekannt: 404.
curl "https://heylinked.io/api/v1/companies/CHE-101.500.085" \
-H "Authorization: Bearer hr_live_…"{
"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
Öffnet die Registerfirma und die Personen dieser Firma. Kostet 5 Credits, ausser die Firma ist in diesem Workspace schon frei. Kein Body.
Parameter
uidpathPflichtDieselbe UID wie beim Lesen.
curl -X POST "https://heylinked.io/api/v1/companies/CHE-101.500.085/unlock" \
-H "Authorization: Bearer hr_live_…"{
"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
Personen suchen
Entscheider im Register. Name, Rolle und Firma sind sichtbar. E-Mail, Telefon und LinkedIn nicht. available sagt nur, ob ein Wert hinterlegt ist.
Parameter
qstringAnfang des Register-Namens. «Hans» findet «Hans Meier». «Meier» findet diesen Namen nicht.
rolestringTeil der Funktion, zum Beispiel Geschäftsführer.
cantonstringKantonskürzel.
citystringOrt, Teilstring.
uidstringUID der Firma, mit oder ohne Formatierung.
sortstringadded, name, city, company. Ohne Angabe: added.
pagenumberAb 1.
page_sizenumber1 bis 50. Standard 25.
curl "https://heylinked.io/api/v1/people?role=Geschäftsführer&canton=BE" \
-H "Authorization: Bearer hr_live_…"{
"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
Eine Person über die id aus der Personensuche. colleagues ist die Zahl der hinterlegten Personen derselben Firma, inklusive dieser.
Parameter
idpathPflichtDie id aus der Personensuche, nicht die UID der Firma.
curl "https://heylinked.io/api/v1/people/8f1c…" \
-H "Authorization: Bearer hr_live_…"{
"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
Öffnet die Person. Kein Pauschalpreis. Eine hinterlegte E-Mail kostet 5 Credits, eine Nummer 5. Das ist getrennt von der Registerfirma. Kein Body.
Parameter
idpathPflichtPersonen-id.
curl -X POST "https://heylinked.io/api/v1/people/8f1c…/unlock" \
-H "Authorization: Bearer hr_live_…"{
"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
Schon geöffnete Firmen
Firmen, die dieser Workspace schon freigeschaltet hat. Kein weiterer Credit. Nützlich, bevor ein Ablauf noch einmal öffnet.
Parameter
pagenumberAb 1.
page_sizenumber1 bis 50. Standard 25.
curl "https://heylinked.io/api/v1/unlocks?page=1&page_size=25" \
-H "Authorization: Bearer hr_live_…"{
"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
Die Werte, die die Suche wirklich versteht. Vor einer Branchensuche aufrufen, damit industry_branch eine id ist und industry ein Label.
Keine Parameter.
curl "https://heylinked.io/api/v1/options" \
-H "Authorization: Bearer hr_live_…"{
"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
Workspace, Credit-Stand und was eine Freischaltung kostet.
Keine Parameter.
curl "https://heylinked.io/api/v1/me" \
-H "Authorization: Bearer hr_live_…"{
"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
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_…"{
"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
Legt einen Entwurf an. Es geht keine Mail raus. Recht: campaigns.
Parameter
namestringPflicht2 bis 80 Zeichen.
subjectstringBetreff des ersten Schritts.
bodystringText 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":"…"}'{ "campaign": { "id": "cmp_…", "name": "Architekten Zürich", "status": "draft" } }Eine Kampagne
Schritte und die ersten 100 Empfänger. Empfänger nur als UID und Status, ohne den Mailtext der Person. Recht: read.
Parameter
idstringPflichtIn der Pfadangabe.
curl "https://heylinked.io/api/v1/campaigns/cmp_…" \
-H "Authorization: Bearer hr_live_…"{
"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
paused und draft stoppen den Versand. active nimmt ihn wieder auf und braucht confirm true, weil dann das eigene Postfach schreibt. Recht: campaigns.
Parameter
statusstringPflichtpaused, draft oder active.
confirmbooleanbei activeMuss 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}'{ "campaign": { "id": "cmp_…", "name": "Architekten Zürich", "status": "active" } }Firmen aufnehmen
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[]Pflicht1 bis 25 UID.
confirmbooleanPflichtMuss 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}'{
"enrolled": [{ "uid": "CHE-101.500.085", "status": "queued" }],
"errors": [],
"charged": 1
}Antworten
Antworten lesen
Die letzten Antworten, Interessensmeldungen, Bounces und Abmeldungen. Optional auf eine Kampagne eingeschränkt. Recht: read.
Parameter
campaign_idstringOhne Angabe: alle Kampagnen des Workspace.
curl "https://heylinked.io/api/v1/replies?campaign_id=cmp_…" \
-H "Authorization: Bearer hr_live_…"{
"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
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_idstringPflichtKampagne, in der die Firma liegt.
uidstringPflichtFirma in dieser Kampagne.
kindstringPflichtinterested 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"}'{ "ok": true, "campaign_id": "cmp_…", "uid": "CHE-101.500.085", "kind": "interested" }Listen und Signale
Listen
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
kindstringcompany oder person.
curl "https://heylinked.io/api/v1/lists?kind=company" \
-H "Authorization: Bearer hr_live_…"{
"lists": [
{ "id": "lst_…", "name": "Zürich IT", "kind": "company", "item_count": 18 }
]
}Gespeicherte Suchen
Gespeicherte Suchen mit dem gespeicherten Filter. Recht: read.
Keine Parameter.
curl "https://heylinked.io/api/v1/saved-searches" \
-H "Authorization: Bearer hr_live_…"{ "searches": [{ "id": "ss_…", "name": "IT Zürich", "query": { "canton": "ZH" } }] }Signale lesen
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_…"{
"signals": [
{ "id": "sig_…", "kind": "external", "company_uid": "CHE-101.500.085", "title": "Demo gebucht" }
]
}Signal anlegen
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.
Parameter
titlestringPflicht3 bis 240 Zeichen.
company_uidstringoder company_nameUID aus dem Bestand.
company_namestringoder company_uidWird einer bekannten Firma zugeordnet, wenn keine UID mitkommt.
idempotency_keystringDieselbe 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"}'{ "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.receivedreply.interestedreply.not_interestedemail.bouncedemail.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 -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"]}'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
uidstringPflichtSchlüssel im Bestand.
uid_formattedstringPflichtLesbare UID.
namestringPflichtFirmenname.
legal_formstringPflichtRechtsform.
statusstringPflichtactive oder ein anderer Registerstatus.
cantonstringPflichtKantonskürzel.
citystringPflichtOrt.
postal_codestringPflichtPLZ.
founded_onstring | nullPflichtISO-Datum, wenn bekannt.
industrystringPflichtHinterlegte Branche.
employee_bandstringPflichtGeschätztes Band, kann leer sein.
revenue_band_estimatedstring | nullPflichtAus dem Mitarbeiterband geschätzt.
unlockedbooleanPflichtOb dieser Workspace die Firma schon geöffnet hat.
has_websitebooleanPflichtOb eine eigene Website bekannt ist. Die Adresse steht hier nicht.
briefstringPflichtEin Satz aus Gründung, Grösse und Zweck.
Firmenprofil, über den Treffer hinaus
purposestringPflichtZweck aus dem Register, wenn vorhanden.
streetstringPflichtStrasse.
legal_namestringPflichtEingetragener Name.
signalsarrayPflichtKurze Fakten. kind ist web, hiring, demand, age oder purpose.
availableobjectnur solange gesperrtwebsite, email, phone, people als Ja/Nein. Keine Werte.
contactobjectnur nach Freischaltungwebsite, email, phone, google_rating, google_rating_count.
peoplearraynur nach Freischaltungname, role, city, und soweit vorhanden email, phone, linkedin_url.
insightsobjectnur nach Freischaltungsummary, revenue_estimate, hiring_signal, services, outreach_signals.
lage.trustobjectPflichtscore und label. Wie belastbar die Einordnung ist.
lage.peersobjectPflichtheadline und detail. Einordnung zur Branche.
lage.imageobjectPflichtlabel und detail zum öffentlichen Bild.
lage.demandobjectPflichtSuchkurve: state, verdict, label, detail, change_pct, topics, lines, months.
lage.supplyobjectPflichtNeugründungen der Branche, Stellenrollen und die BFS-Reihe des Sektors. Das beschreibt den Sektor, nicht immer die einzelne Firma.
Person
idstringPflichtFür GET und POST /people/{id}.
rolestring | nullPflichtFunktion im Register.
companyobjectPflichtuid, name, legal_form, city, canton, industry.
availableobjectnur solange gesperrtemail, phone, linkedin als Ja/Nein.
contactobjectnur nach Freischaltungemail, email_status, phone, linkedin_url. Leer heisst: nicht hinterlegt.
colleaguesnumbernur bei GET einer PersonPersonen derselben Firma, inklusive dieser.
Fehler
Der HTTP-Status passt zum Fall. code bleibt stabil, message ist für Menschen.
- 401
unauthorizedSchlüssel fehlt, ist falsch oder widerrufen.
- 400
bad_requestParameter unbrauchbar. message sagt, welches Feld.
- 404
not_foundUID oder Person nicht im Bestand.
- 402
insufficient_creditsFreischaltung ohne Guthaben. Nichts wurde geöffnet.
- 400
confirmation_requiredactive, das Aufnehmen von Firmen oder ein Webhook aus dem Assistenten ohne confirm true.
- 403
forbidden_scopeDer Schlüssel hat das Recht nicht: read, unlock, campaigns oder signals.
- 429
rate_limitedMehr als 120 Anfragen in einer Minute für diesen Schlüssel.
- 500
errorDie 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.
{
"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.

