HeyLinked API, MCP and CLI
Search Swiss companies and people, open contacts, run campaigns and read replies. From your own code, from the terminal, from Cursor, Claude or ChatGPT, or from Make, Zapier and n8n.
Search and reading a locked profile are free. Opening a registry company costs 5 credits. Opening a person costs 5 credits for an email on file and 5 for a number. A second open of the same record in the same workspace costs nothing.
- Base URL
- https://heylinked.io/api/v1
- MCP
- https://heylinked.io/api/mcp
- CLI
- npm install -g @heylinked/cli
- OpenAPI
- https://heylinked.io/api/v1/openapi.json
- Header
- Authorization: Bearer hr_live_…
- Format
- JSON
- Limit
- 120 requests per minute per key
Quick start
First see who matches. Then read one firm. Open it only when it counts.
- 1
Create a key
Settings → API & MCP. It starts with hr_live_.
- 2
Search
For example IT firms in Zurich with a website. Free.
- 3
Read
Take the UID from the first hit. While it is locked you see available, not the email.
- 4
Open
POST …/unlock. The response carries charged, the new balance and the full profile.
# 1 Search
curl "https://heylinked.io/api/v1/companies?canton=ZH&industry_branch=it&has_website=yes" \
-H "Authorization: Bearer hr_live_…"
# 2 Read
curl "https://heylinked.io/api/v1/companies/CHE-101.500.085" \
-H "Authorization: Bearer hr_live_…"
# 3 Open
curl -X POST "https://heylinked.io/api/v1/companies/CHE-101.500.085/unlock" \
-H "Authorization: Bearer hr_live_…"Keys
Under Settings → API & MCP choose a name and create the key. It starts with hr_live_ and is shown only this once. What is stored is the hash. Revocation takes effect immediately. A workspace can have 10 active keys. The same key works for REST and MCP.
Authentication
Send the key on every request to /api/v1 and on tools/list and tools/call. Missing or revoked keys return 401. More than 120 requests in one minute for one key return 429. Responses are JSON. The endpoints send Access-Control-Allow-Origin: *, which does not replace the key.
Scopes
readSearch, profiles, lists, saved searches, campaigns, replies, signals.
unlockOpens a company or a person. Costs credits.
campaignsDrafts, status, enrolling companies, marking interest, managing webhooks.
signalsPosts an inbound event, for example from a shop or the CRM.
A missing scope returns 403 forbidden_scope.
Authorization: Bearer hr_live_…Connect MCP
The server speaks streamable HTTP, stateless, JSON-RPC 2.0, at https://heylinked.io/api/mcp. A GET on that address lists the tool names.
Cursor sends the key in the header. One entry in the MCP settings.
Claude and ChatGPT get a 401 on the first call that points to the OAuth metadata. The person signs in at HeyLinked and confirms workspace and scopes. No key in the chat.
The protocol is 2025-03-26. A client that asks for 2024-11-05 gets that version. text is a JSON string, the same body as the matching REST call. isError is true when the arguments are unusable, the UID is missing or the unlock has no credits.
{
"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
}
}Tools
23 tools. Each needs the scope shown next to it. The descriptions are the German text the server returns to the assistant.
set_campaign_status with active, enroll_companies and create_webhook only run when the arguments include confirm: true. Creating a draft sends nothing.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.
Install the CLI
heylinked brings every REST call to the terminal. It needs Node.js 20 or later and has no further dependencies. Output is JSON, so it fits into scripts, CI jobs and coding agents like Claude Code or Cursor, which run shell commands anyway.
Sign in
auth loginOpens the browser. Sign in at HeyLinked, confirm workspace and scopes. OAuth with PKCE, the access renews itself.
auth login --key hr_live_…A key from Settings → API & MCP. Checked against /api/v1/me before it is stored.
auth login --with-tokenReads the key from stdin, so it does not end up in the shell history.
--no-browserPrints the sign-in address instead, for a server over SSH.
Credentials live in ~/.config/heylinked/config.json, readable only by you. One profile per workspace, for example per client. auth logout removes it.
Environment
HEYLINKED_API_KEYstringoptionalTakes precedence over any stored profile. For CI.
HEYLINKED_PROFILEstringoptionalPick a profile, like --profile.
HEYLINKED_BASE_URLurloptionalAnother server, like --base-url. Default is https://heylinked.io.
npm install -g @heylinked/cli
heylinked auth login
heylinked auth statusheylinked auth login --profile kunde-a
heylinked auth login --profile kunde-b --key hr_live_…
heylinked auth list
heylinked auth use kunde-a
heylinked campaigns list --profile kunde-bCommands
Flags become API fields: --industry-branch it is sent as industry_branch=it. GET commands send them as query, POST commands as a JSON body. Lists like --events take commas. --data merges a JSON body, from a file with @datei.json or from stdin with -. Each endpoint above shows its command in the CLI tab.
Sign in
heylinked auth loginOpens the browser, OAuth with PKCE. With --key hr_live_… a key instead.
heylinked auth statusProfile, sign-in type, workspace and balance.
heylinked auth list · auth use <profil>List and switch profiles, for example per client.
heylinked auth logoutRemoves the profile from this machine.
Data
heylinked companies search · get · unlockSearch, read and open companies. Filters as flags, for example --canton ZH.
heylinked people search · get · unlockSearch, read and open decision makers.
heylinked unlocks list · options · meAlready opened, filter values and balance.
Work
heylinked campaigns list · get · createRead campaigns and create drafts. A draft sends nothing.
heylinked campaigns status · enrollControl sending and enroll companies. active and enroll need --confirm.
heylinked replies list · markRead replies, mark interest.
heylinked lists list · get · searches listLists, their entries and saved searches.
heylinked signals list · createRead signals and post them from outside.
heylinked webhooks list · create · deleteManage addresses for Make, Zapier and n8n.
Raw access
heylinked api <METHODE> <pfad>Any endpoint, with -q key=value and --data '{…}', @file.json or - for stdin.
heylinked endpointsReads the OpenAPI description live and lists every endpoint with its command.
# UIDs of IT firms in Zurich
heylinked companies search --canton ZH --industry-branch it \
--compact | jq -r '.items[].uid'
# Opened firms into a campaign, at most 25
heylinked campaigns enroll cmp_… $(heylinked unlocks list \
--compact | jq -r '.items[].uid' | head -25) --confirm
# Any endpoint, raw
heylinked api GET /companies -q canton=ZH -q page=2
heylinked api POST /signals --data @signal.jsonOutput and exit codes
Results go to stdout as JSON, --compact puts them on one line. Errors go to stderr as JSON with the same code as the API. The exit code says what happened, without parsing text.
- 0
okSuccess. JSON on stdout.
- 1
errorNetwork or unknown error.
- 2
usageWrong command or argument. Nothing was sent.
- 3
unauthorized401. Not signed in or access expired.
- 4
forbidden_scope403. The access lacks the scope.
- 5
not_found404. UID, person or campaign unknown.
- 6
insufficient_credits402. No balance, nothing was opened.
- 7
bad_request400. Parameter unusable.
- 8
confirmation_required400. --confirm is missing.
- 9
rate_limited429, after three retries.
- 10
server_error5xx, after retries on safe calls.
$ heylinked me
{
"error": {
"code": "unauthorized",
"message": "Nicht angemeldet. heylinked auth login",
"status": 401
}
}
$ echo $?
3Companies
Search companies
Register data, industry, short text and whether a website is known. No email, no phone, no people. Search is free.
Parameters
qstringStart of the company name, a UID, or an industry term the taxonomy knows. If HeyLinked knows the text as an industry, q searches that industry. Otherwise the start of the name. Place is city.
cantonstringCanton code, for example ZH. A written-out name returns 400.
citystringPlace, substring.
postal_codestringFour-digit postcode.
industry_branchstringid of an industry group from GET /api/v1/options, for example immobilien or bau.
industrystringExact sub-industry label from the same list. Together with industry_branch, both must match.
legal_formstringFor example AG or GmbH.
employee_bandstring1-10, 11-20, 21-50, 51-100, 101-250, 251+. An estimate. If revenue_band is also set, this band wins.
revenue_bandstring<0.5M, 0.5-2M, 2-10M, 10-50M, 50M+. Estimated from the employee band, not a reported turnover.
founded_fromnumberYear, inclusive.
founded_tonumberYear, inclusive.
company_agestringnew_7d, new_30d, new_12m, new_24m, new_36m, new_5y, age_10y_plus, age_25y_plus. Intersects with founded_from and founded_to.
has_websitestringyes or no.
unlock_statusstringunlocked or locked, for this workspace.
sourcestringzefix (commercial register), google_local or web.
sortstringname, city, founded, added. Default: founded.
pagenumberFrom 1. Default 1.
page_sizenumber1 to 50. Default 25. MCP search defaults to 15 when the assistant sets nothing.
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
}Read one company
Profile for a UID: register, short text, signals and situation. While the company is locked, available only says whether a website, email, phone or people exist.
Parameters
uidpathrequiredWith or without formatting. HeyLinked normalises it. Unknown: 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": ""
}
}
}
}
}Unlock a company
Opens the registry company and the people on it. Costs 5 credits, unless this workspace already owns the company. No body.
Parameters
uidpathrequiredThe same UID as when reading.
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": []
}
}
}People
Search people
Decision-makers on the register. Name, role and company are visible. Email, phone and LinkedIn are not. available only says whether a value is on file.
Parameters
qstringStart of the registered name. “Hans” finds “Hans Meier”. “Meier” does not find that name.
rolestringPart of the role, for example Geschäftsführer.
cantonstringCanton code.
citystringPlace, substring.
uidstringCompany UID, with or without formatting.
sortstringadded, name, city, company. Default: added.
pagenumberFrom 1.
page_sizenumber1 to 50. Default 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
}Read one person
One person by the id from people search. colleagues is how many people at the same company are on file, including this one.
Parameters
idpathrequiredThe id from people search, not the company UID.
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" }
}
}Unlock a person
Opens this person. No flat fee. An email on file costs 5 credits, a number 5. This is separate from the registry company. No body.
Parameters
idpathrequiredPerson 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"
}
}
}Account
Companies already open
Companies this workspace has already unlocked. No further credit. Useful before a flow opens one again.
Parameters
pagenumberFrom 1.
page_sizenumber1 to 50. Default 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
}Filter values
The values search actually understands. Call this before an industry search, so industry_branch is an id and industry is a label.
No parameters.
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." }
}Account
Workspace, credit balance and what an unlock costs.
No parameters.
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
}Campaigns
List campaigns
Campaigns in this workspace. Status, subject, recipient count, and whether mail was sent, opened or answered. No sending. Scope: read.
No parameters.
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
}
]
}Create a campaign
Creates a draft. No mail goes out. Scope: campaigns.
Parameters
namestringrequired2 to 80 characters.
subjectstringSubject of the first step.
bodystringBody of the first step.
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" } }One campaign
Steps and the first 100 recipients. Recipients only as UID and status, without that person's mail text. Scope: read.
Parameters
idstringrequiredIn the path.
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
}Pause or resume sending
paused and draft stop sending. active resumes it and needs confirm true, because the workspace mailbox then writes. Scope: campaigns.
Parameters
statusstringrequiredpaused, draft or active.
confirmbooleanwhen activeMust be true, otherwise 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" } }Enroll companies
Enrolls companies that are already unlocked. At most 25 UIDs. confirm must be true, because each new company spends recipient credits. Scope: campaigns.
Parameters
uidsstring[]required1 to 25 UIDs.
confirmbooleanrequiredMust be true.
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
}Replies
Read replies
The latest replies, interest marks, bounces and unsubscribes. Optionally limited to one campaign. Scope: read.
Parameters
campaign_idstringOmitted: every campaign in the 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"
}
]
}Mark interest
Sets a company to interested or not_interested. A mail must already have been sent. Fires the same webhook as a mark in the product. Scope: campaigns.
Parameters
campaign_idstringrequiredCampaign the company belongs to.
uidstringrequiredCompany in that campaign.
kindstringrequiredinterested or 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" }Lists and signals
Lists
Lists in the workspace. kind filters to company or person. Members of one list are at /api/v1/lists/{id}. An email is included only when that company is already unlocked. Scope: read.
Parameters
kindstringcompany or 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 }
]
}Saved searches
Saved searches with the stored filter. Scope: read.
No parameters.
curl "https://heylinked.io/api/v1/saved-searches" \
-H "Authorization: Bearer hr_live_…"{ "searches": [{ "id": "ss_…", "name": "IT Zürich", "query": { "canton": "ZH" } }] }Read signals
The latest signals attached to this workspace. Costs no credit. Scope: read.
No parameters.
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" }
]
}Create a signal
Your shop, site or CRM reports an event against a company. Costs no credit. An unknown UID is rejected. The same idempotency_key creates the signal only once. Scope: signals.
Parameters
titlestringrequired3 to 240 characters.
company_uidstringor company_nameUID from the database.
company_namestringor company_uidMatched to a known company when no UID is sent.
idempotency_keystringThe same company and key only once.
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
One HTTPS address receives replies, interest, bounces and unsubscribes. Zapier (Webhooks by Zapier), Make (HTTP) and n8n all use that same address. No app on their side. Create it under Settings → API, or with POST /api/v1/webhooks and the campaigns scope. The secret is returned once on create and stays visible to admins.
Events
reply.receivedreply.interestedreply.not_interestedemail.bouncedemail.unsubscribed
Verify the signature
X-HeyLinked-Signature is HMAC-SHA256 with the secret over {timestamp}.{raw body}. Compare it before you trust the payload. A missing events list on create means every event.
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
}Fields
A search hit is the short row. A company profile adds register text, signals and the situation. Contact, people and insights appear only after the company unlock. A person from people search stays closed until that person is unlocked.
Search hit
uidstringrequiredKey in the database.
uid_formattedstringrequiredReadable UID.
namestringrequiredCompany name.
legal_formstringrequiredLegal form.
statusstringrequiredactive or another register status.
cantonstringrequiredCanton code.
citystringrequiredPlace.
postal_codestringrequiredPostcode.
founded_onstring | nullrequiredISO date, when known.
industrystringrequiredIndustry on file.
employee_bandstringrequiredEstimated band, can be empty.
revenue_band_estimatedstring | nullrequiredEstimated from the employee band.
unlockedbooleanrequiredWhether this workspace has already opened the company.
has_websitebooleanrequiredWhether an own website is known. The address is not here.
briefstringrequiredOne sentence from founding, size and purpose.
Company profile, beyond the hit
purposestringrequiredPurpose from the register, when present.
streetstringrequiredStreet.
legal_namestringrequiredRegistered name.
signalsarrayrequiredShort facts. kind is web, hiring, demand, age or purpose.
availableobjectonly while lockedwebsite, email, phone, people as yes/no. No values.
contactobjectonly after unlockwebsite, email, phone, google_rating, google_rating_count.
peoplearrayonly after unlockname, role, city, and where present email, phone, linkedin_url.
insightsobjectonly after unlocksummary, revenue_estimate, hiring_signal, services, outreach_signals.
lage.trustobjectrequiredscore and label. How reliable the classification is.
lage.peersobjectrequiredheadline and detail. How the company sits in its industry.
lage.imageobjectrequiredlabel and detail of the public image.
lage.demandobjectrequiredSearch curve: state, verdict, label, detail, change_pct, topics, lines, months.
lage.supplyobjectrequiredNew incorporations in the industry, job roles and the FSO series for the sector. That describes the sector, not always the individual company.
Person
idstringrequiredFor GET and POST /people/{id}.
rolestring | nullrequiredRole on the register.
companyobjectrequireduid, name, legal_form, city, canton, industry.
availableobjectonly while lockedemail, phone, linkedin as yes/no.
contactobjectonly after unlockemail, email_status, phone, linkedin_url. Empty means: not on file.
colleaguesnumberonly on GET of one personPeople at the same company, including this one.
Errors
The HTTP status matches the case. code is stable, message is for people.
- 401
unauthorizedKey is missing, wrong or revoked.
- 400
bad_requestParameter unusable. message says which field.
- 404
not_foundUID or person is not in the database.
- 402
insufficient_creditsUnlock without balance. Nothing was opened.
- 400
confirmation_requiredactive, enrolling companies, or a webhook from the assistant without confirm true.
- 403
forbidden_scopeThe key lacks the scope: read, unlock, campaigns or signals.
- 429
rate_limitedMore than 120 requests in one minute for this key.
- 500
errorThe request failed.
The employee count is an estimate. Job roles and the FSO row describe the industry and the sector, not always the individual company. An unlock does not promise a verified address.
{
"error": {
"code": "bad_request",
"message": "canton ist ein Kantonskürzel, zum Beispiel ZH, BE oder GE."
}
}OpenAPI
https://heylinked.io/api/v1/openapi.json describes every endpoint in OpenAPI 3.1, without a key. Each operation carries its scope in x-heylinked-scope and its CLI command in x-heylinked-cli. Import it into Postman or Insomnia, or generate a client from it.
curl "https://heylinked.io/api/v1/openapi.json"Questions
How do I get an API key?
In the workspace under Settings → API & MCP. The key is shown in full only once and can be revoked at any time. A workspace can have 10 active keys.
Can I search first, and nothing else?
Yes. Search and reading a locked profile are free. You open the dossier only when the company matters. Opening a person is its own credit.
What is the difference between the API and MCP?
The REST API is for your own programs. MCP exposes the same calls as tools. Cursor uses the API key. Claude and ChatGPT sign the person in with OAuth. Search, lists, campaigns and replies are the same.
What is the CLI for?
For the terminal, scripts, CI and coding agents like Claude Code. heylinked auth login signs in through the browser, then every endpoint is a command with JSON output and fixed exit codes. It uses the same API, the same scopes and the same credits.
Is there a rate limit?
Yes. Each API key allows at most 120 requests per minute. After that the API responds with 429.
Is the people hit count exact?
For companies, total is the hit count. For people, total is a database estimate. The rows on the page are the real hits.
Can I connect HeyLinked to my CRM?
Yes, through one address. HeyLinked sends replies, interest, bounces and unsubscribes to Make, Zapier or n8n. That scenario then writes to HubSpot, Pipedrive or Salesforce. There is no app inside those systems for this.
Can an assistant start a campaign?
It can search, read lists and campaigns, and create a draft. Pausing stops sending. Resuming and enrolling companies only run with confirm true, so credits and mail are not spent without a limit.

