Overview

HeyLinked API and MCP

Search Swiss companies and people, open contacts, run campaigns and read replies. From your own code, 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
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. 1

    Create a key

    Settings → API & MCP. It starts with hr_live_.

  2. 2

    Search

    For example IT firms in Zurich with a website. Free.

  3. 3

    Read

    Take the UID from the first hit. While it is locked you see available, not the email.

  4. 4

    Open

    POST …/unlock. The response carries charged, the new balance and the full profile.

Three calls
# 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

  • read

    Search, profiles, lists, saved searches, campaigns, replies, signals.

  • unlock

    Opens a company or a person. Costs credits.

  • campaigns

    Drafts, status, enrolling companies, marking interest, managing webhooks.

  • signals

    Posts an inbound event, for example from a shop or the CRM.

A missing scope returns 403 forbidden_scope.

Header
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_…"
      }
    }
  }
}
Shape of a tool result
{
  "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_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.

Companies

Search the commercial register, read a profile, open contacts.

Search companies

GET/api/v1/companies

Register data, industry, short text and whether a website is known. No email, no phone, no people. Search is free.

The values above show the shape. They are not a slice of the database. total is the hit count. Page forward until items is empty or page * page_size reaches total.

Parameters

  • qstring

    Start 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.

  • cantonstring

    Canton code, for example ZH. A written-out name returns 400.

  • citystring

    Place, substring.

  • postal_codestring

    Four-digit postcode.

  • industry_branchstring

    id of an industry group from GET /api/v1/options, for example immobilien or bau.

  • industrystring

    Exact sub-industry label from the same list. Together with industry_branch, both must match.

  • legal_formstring

    For example AG or GmbH.

  • employee_bandstring

    1-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_fromnumber

    Year, inclusive.

  • founded_tonumber

    Year, inclusive.

  • company_agestring

    new_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_websitestring

    yes or no.

  • unlock_statusstring

    unlocked or locked, for this workspace.

  • sourcestring

    zefix (commercial register), google_local or web.

  • sortstring

    name, city, founded, added. Default: founded.

  • pagenumber

    From 1. Default 1.

  • page_sizenumber

    1 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_…"
Example response
{
  "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

GET/api/v1/companies/{uid}

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.

The first call for a company can take a few seconds, because search, jobs and FSO data are read and then cached. Empty fields stay empty.

Parameters

  • uidpathrequired

    With or without formatting. HeyLinked normalises it. Unknown: 404.

curl "https://heylinked.io/api/v1/companies/CHE-101.500.085" \
  -H "Authorization: Bearer hr_live_…"
Example, company still locked
{
  "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

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

Opens the registry company and the people on it. Costs 5 credits, unless this workspace already owns the company. No body.

company is then the same full profile as GET. A second call sets charged to 0 and already_owned to true. Too few credits: 402, and the company stays locked. An unlock does not guarantee a verified email.

Parameters

  • uidpathrequired

    The same UID as when reading.

curl -X POST "https://heylinked.io/api/v1/companies/CHE-101.500.085/unlock" \
  -H "Authorization: Bearer hr_live_…"
Example response
{
  "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

Decision makers by role and region. Opening a person is its own credit.

Search people

GET/api/v1/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.

total for people is a database estimate, not an exact count. Company search does not name these people. An opened company dossier includes them where they are on file for that company.

Parameters

  • qstring

    Start of the registered name. “Hans” finds “Hans Meier”. “Meier” does not find that name.

  • rolestring

    Part of the role, for example Geschäftsführer.

  • cantonstring

    Canton code.

  • citystring

    Place, substring.

  • uidstring

    Company UID, with or without formatting.

  • sortstring

    added, name, city, company. Default: added.

  • pagenumber

    From 1.

  • page_sizenumber

    1 to 50. Default 25.

curl "https://heylinked.io/api/v1/people?role=Geschäftsführer&canton=BE" \
  -H "Authorization: Bearer hr_live_…"
Example response
{
  "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

GET/api/v1/people/{id}

One person by the id from people search. colleagues is how many people at the same company are on file, including this one.

Parameters

  • idpathrequired

    The id from people search, not the company UID.

curl "https://heylinked.io/api/v1/people/8f1c…" \
  -H "Authorization: Bearer hr_live_…"
Example response
{
  "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

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

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.

If the address is missing, the field is null. A second call charges nothing again.

Parameters

  • idpathrequired

    Person id.

curl -X POST "https://heylinked.io/api/v1/people/8f1c…/unlock" \
  -H "Authorization: Bearer hr_live_…"
Example response
{
  "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

What is already open, which filter values exist, and the balance.

Companies already open

GET/api/v1/unlocks

Companies this workspace has already unlocked. No further credit. Useful before a flow opens one again.

Parameters

  • pagenumber

    From 1.

  • page_sizenumber

    1 to 50. Default 25.

curl "https://heylinked.io/api/v1/unlocks?page=1&page_size=25" \
  -H "Authorization: Bearer hr_live_…"
Example response
{
  "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

GET/api/v1/options

The values search actually understands. Call this before an industry search, so industry_branch is an id and industry is a label.

The list above is shortened. The real response contains every canton, industry group and sub-industry.

No parameters.

curl "https://heylinked.io/api/v1/options" \
  -H "Authorization: Bearer hr_live_…"
Shape of the response
{
  "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

GET/api/v1/me

Workspace, credit balance and what an unlock costs.

No parameters.

curl "https://heylinked.io/api/v1/me" \
  -H "Authorization: Bearer hr_live_…"
Example response
{
  "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

Read campaigns, create drafts, pause and resume sending, enroll companies. Scope campaigns for writing.

List campaigns

GET/api/v1/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_…"
Example response
{
  "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

POST/api/v1/campaigns

Creates a draft. No mail goes out. Scope: campaigns.

Parameters

  • namestringrequired

    2 to 80 characters.

  • subjectstring

    Subject of the first step.

  • bodystring

    Body 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":"…"}'
Example response, status 201
{ "campaign": { "id": "cmp_…", "name": "Architekten Zürich", "status": "draft" } }

One campaign

GET/api/v1/campaigns/{id}

Steps and the first 100 recipients. Recipients only as UID and status, without that person's mail text. Scope: read.

Parameters

  • idstringrequired

    In the path.

curl "https://heylinked.io/api/v1/campaigns/cmp_…" \
  -H "Authorization: Bearer hr_live_…"
Shape of the response
{
  "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

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

paused and draft stop sending. active resumes it and needs confirm true, because the workspace mailbox then writes. Scope: campaigns.

Parameters

  • statusstringrequired

    paused, draft or active.

  • confirmbooleanwhen active

    Must 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}'
Example response
{ "campaign": { "id": "cmp_…", "name": "Architekten Zürich", "status": "active" } }

Enroll companies

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

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[]required

    1 to 25 UIDs.

  • confirmbooleanrequired

    Must 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}'
Example response
{
  "enrolled": [{ "uid": "CHE-101.500.085", "status": "queued" }],
  "errors": [],
  "charged": 1
}

Replies

Replies, interest, bounces and unsubscribes across campaigns.

Read replies

GET/api/v1/replies

The latest replies, interest marks, bounces and unsubscribes. Optionally limited to one campaign. Scope: read.

Parameters

  • campaign_idstring

    Omitted: every campaign in the workspace.

curl "https://heylinked.io/api/v1/replies?campaign_id=cmp_…" \
  -H "Authorization: Bearer hr_live_…"
Example response
{
  "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

POST/api/v1/replies

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_idstringrequired

    Campaign the company belongs to.

  • uidstringrequired

    Company in that campaign.

  • kindstringrequired

    interested 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"}'
Example response
{ "ok": true, "campaign_id": "cmp_…", "uid": "CHE-101.500.085", "kind": "interested" }

Lists and signals

Lists and saved searches from the workspace. Signals from outside, for example a booked demo.

Lists

GET/api/v1/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

  • kindstring

    company or person.

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

Saved searches

GET/api/v1/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_…"
Shape of the response
{ "searches": [{ "id": "ss_…", "name": "IT Zürich", "query": { "canton": "ZH" } }] }

Read signals

GET/api/v1/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_…"
Shape of the response
{
  "signals": [
    { "id": "sig_…", "kind": "external", "company_uid": "CHE-101.500.085", "title": "Demo gebucht" }
  ]
}

Create a signal

POST/api/v1/signals

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.

The same idempotency_key again returns duplicate true and status 200. The call stays free.

Parameters

  • titlestringrequired

    3 to 240 characters.

  • company_uidstringor company_name

    UID from the database.

  • company_namestringor company_uid

    Matched to a known company when no UID is sent.

  • idempotency_keystring

    The 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"}'
Example response, status 201
{ "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.received
  • reply.interested
  • reply.not_interested
  • email.bounced
  • email.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
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"]}'
Delivery
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

  • uidstringrequired

    Key in the database.

  • uid_formattedstringrequired

    Readable UID.

  • namestringrequired

    Company name.

  • legal_formstringrequired

    Legal form.

  • statusstringrequired

    active or another register status.

  • cantonstringrequired

    Canton code.

  • citystringrequired

    Place.

  • postal_codestringrequired

    Postcode.

  • founded_onstring | nullrequired

    ISO date, when known.

  • industrystringrequired

    Industry on file.

  • employee_bandstringrequired

    Estimated band, can be empty.

  • revenue_band_estimatedstring | nullrequired

    Estimated from the employee band.

  • unlockedbooleanrequired

    Whether this workspace has already opened the company.

  • has_websitebooleanrequired

    Whether an own website is known. The address is not here.

  • briefstringrequired

    One sentence from founding, size and purpose.

Company profile, beyond the hit

  • purposestringrequired

    Purpose from the register, when present.

  • streetstringrequired

    Street.

  • legal_namestringrequired

    Registered name.

  • signalsarrayrequired

    Short facts. kind is web, hiring, demand, age or purpose.

  • availableobjectonly while locked

    website, email, phone, people as yes/no. No values.

  • contactobjectonly after unlock

    website, email, phone, google_rating, google_rating_count.

  • peoplearrayonly after unlock

    name, role, city, and where present email, phone, linkedin_url.

  • insightsobjectonly after unlock

    summary, revenue_estimate, hiring_signal, services, outreach_signals.

  • lage.trustobjectrequired

    score and label. How reliable the classification is.

  • lage.peersobjectrequired

    headline and detail. How the company sits in its industry.

  • lage.imageobjectrequired

    label and detail of the public image.

  • lage.demandobjectrequired

    Search curve: state, verdict, label, detail, change_pct, topics, lines, months.

  • lage.supplyobjectrequired

    New incorporations in the industry, job roles and the FSO series for the sector. That describes the sector, not always the individual company.

Person

  • idstringrequired

    For GET and POST /people/{id}.

  • rolestring | nullrequired

    Role on the register.

  • companyobjectrequired

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

  • availableobjectonly while locked

    email, phone, linkedin as yes/no.

  • contactobjectonly after unlock

    email, email_status, phone, linkedin_url. Empty means: not on file.

  • colleaguesnumberonly on GET of one person

    People at the same company, including this one.

Errors

The HTTP status matches the case. code is stable, message is for people.

  • 401
    unauthorized

    Key is missing, wrong or revoked.

  • 400
    bad_request

    Parameter unusable. message says which field.

  • 404
    not_found

    UID or person is not in the database.

  • 402
    insufficient_credits

    Unlock without balance. Nothing was opened.

  • 400
    confirmation_required

    active, enrolling companies, or a webhook from the assistant without confirm true.

  • 403
    forbidden_scope

    The key lacks the scope: read, unlock, campaigns or signals.

  • 429
    rate_limited

    More than 120 requests in one minute for this key.

  • 500
    error

    The 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 body
{
  "error": {
    "code": "bad_request",
    "message": "canton ist ein Kantonskürzel, zum Beispiel ZH, BE oder GE."
  }
}

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.

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.