API and MCP reference

Endpoints, parameters, fields and examples. The same Swiss companies and decision-makers as in HeyReach.

Overview

Base address https://heyreach.ch. The same paths apply on a local server. Every call uses Authorization: Bearer hr_live_….

Search and reading a locked profile are free. They return register data, a short text and whether contacts exist. Opening a company costs 1 credit and returns the dossier, researched contacts and the people on that company. Opening one person costs 1 credit and returns that person’s email, phone and LinkedIn, where we have them. A second open of the same record in the same workspace costs nothing.

MCP is the same database for assistants. The tools call these endpoints. The credit is the same credit.

Quick start

Three calls. First see who matches. Then read one firm. Open it only when it counts.

  1. Search, for example IT firms in Zurich with a website.
  2. Read the UID from the first hit. While it is locked you see available, not the email.
  3. POST …/unlock. The response carries charged, the new balance and the full profile.
curl "https://heyreach.ch/api/v1/companies?canton=ZH&industry_branch=it&has_website=yes" \
  -H "Authorization: Bearer hr_live_…"

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

curl -X POST "https://heyreach.ch/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.

Authorization: Bearer hr_live_…

Responses are JSON. Browsers may call the API from another origin: the endpoints send Access-Control-Allow-Origin: *. That does not replace the key.

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.

curl "https://heyreach.ch/api/v1/companies?canton=ZH&industry_branch=it&employee_band=11-20&has_website=yes&founded_from=2018" \
  -H "Authorization: Bearer hr_live_…"
ParameterTypeRequiredMeaning
qstringnoStart of the company name, a UID, or an industry term the taxonomy knows. If HeyReach knows the text as an industry, q searches that industry. Otherwise the start of the name. Place is city.
cantonstringnoCanton code, for example ZH. A written-out name returns 400.
citystringnoPlace, substring.
postal_codestringnoFour-digit postcode.
industry_branchstringnoid of an industry group from GET /api/v1/options, for example immobilien or bau.
industrystringnoExact sub-industry label from the same list. Together with industry_branch, both must match.
legal_formstringnoFor example AG or GmbH.
employee_bandstringno1-10, 11-20, 21-50, 51-100, 101-250, 251+. An estimate. If revenue_band is also set, this band wins.
revenue_bandstringno<0.5M, 0.5-2M, 2-10M, 10-50M, 50M+. Estimated from the employee band, not a reported turnover.
founded_fromnumbernoYear, inclusive.
founded_tonumbernoYear, inclusive.
company_agestringnonew_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_websitestringnoyes or no.
unlock_statusstringnounlocked or locked, for this workspace.
sourcestringnozefix (commercial register), google_local or web.
sortstringnoname, city, founded, added. Default: founded.
pagenumbernoFrom 1. Default 1.
page_sizenumberno1 to 50. Default 25. MCP search defaults to 15 when the assistant sets nothing.

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
}

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.

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.

curl "https://heyreach.ch/api/v1/companies/CHE-101.500.085" \
  -H "Authorization: Bearer hr_live_…"
ParameterTypeRequiredMeaning
uidpathyesWith or without formatting. HeyReach normalises it. Unknown: 404.

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": ""
        }
      }
    }
  }
}

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.

Unlock a company

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

Opens the dossier, researched contacts and the people on this company. Costs 1 credit, unless this workspace already owns the company. No body.

curl -X POST "https://heyreach.ch/api/v1/companies/CHE-101.500.085/unlock" \
  -H "Authorization: Bearer hr_live_…"
ParameterTypeRequiredMeaning
uidpathyesThe same UID as when reading.

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": []
    }
  }
}

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.

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.

curl "https://heyreach.ch/api/v1/people?role=Geschäftsführer&canton=BE" \
  -H "Authorization: Bearer hr_live_…"
ParameterTypeRequiredMeaning
qstringnoStart of the registered name. “Hans” finds “Hans Meier”. “Meier” does not find that name.
rolestringnoPart of the role, for example Geschäftsführer.
cantonstringnoCanton code.
citystringnoPlace, substring.
uidstringnoCompany UID, with or without formatting.
sortstringnoadded, name, city, company. Default: added.
pagenumbernoFrom 1.
page_sizenumberno1 to 50. Default 25.

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
}

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.

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.

curl "https://heyreach.ch/api/v1/people/8f1c…" \
  -H "Authorization: Bearer hr_live_…"
ParameterTypeRequiredMeaning
idpathyesThe id from people search, not the company UID.

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’s email, phone and LinkedIn, where we have them. Costs 1 credit, unless they are already open. This is separate from unlocking the company. No body.

curl -X POST "https://heyreach.ch/api/v1/people/8f1c…/unlock" \
  -H "Authorization: Bearer hr_live_…"
ParameterTypeRequiredMeaning
idpathyesPerson id.

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"
    }
  }
}

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

Companies already open

GET/api/v1/unlocks

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

curl "https://heyreach.ch/api/v1/unlocks?page=1&page_size=25" \
  -H "Authorization: Bearer hr_live_…"
ParameterTypeRequiredMeaning
pagenumbernoFrom 1.
page_sizenumberno1 to 50. Default 25.

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.

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

No parameters.

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": 1, "person_unlock": 1 },
  "notes": { "q": "Anfang des Firmennamens, eine UID, oder ein Branchenbegriff." }
}

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

Account

GET/api/v1/me

Workspace, credit balance and what an unlock costs.

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

No parameters.

Example response

{
  "workspace_id": "ws_…",
  "balance": 10,
  "unlock_credit_cost": 1,
  "person_unlock_credit_cost": 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

FieldTypeRequiredMeaning
uidstringalwaysKey in the database.
uid_formattedstringalwaysReadable UID.
namestringalwaysCompany name.
legal_formstringalwaysLegal form.
statusstringalwaysactive or another register status.
cantonstringalwaysCanton code.
citystringalwaysPlace.
postal_codestringalwaysPostcode.
founded_onstring | nullalwaysISO date, when known.
industrystringalwaysIndustry on file.
employee_bandstringalwaysEstimated band, can be empty.
revenue_band_estimatedstring | nullalwaysEstimated from the employee band.
unlockedbooleanalwaysWhether this workspace has already opened the company.
has_websitebooleanalwaysWhether an own website is known. The address is not here.
briefstringalwaysOne sentence from founding, size and purpose.

Company profile, beyond the hit

FieldTypeRequiredMeaning
purposestringalwaysPurpose from the register, when present.
streetstringalwaysStreet.
legal_namestringalwaysRegistered name.
signalsarrayalwaysShort 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.trustobjectalwaysscore and label. How reliable the classification is.
lage.peersobjectalwaysheadline and detail. How the company sits in its industry.
lage.imageobjectalwayslabel and detail of the public image.
lage.demandobjectalwaysSearch curve: state, verdict, label, detail, change_pct, topics, lines, months.
lage.supplyobjectalwaysNew incorporations in the industry, job roles and the FSO series for the sector. That describes the sector, not always the individual company.

Person

FieldTypeRequiredMeaning
idstringalwaysFor GET and POST /people/{id}.
rolestring | nullalwaysRole on the register.
companyobjectalwaysuid, 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.

MCP

The server speaks streamable HTTP, stateless, JSON-RPC 2.0. Address: https://heyreach.ch/api/mcp. A GET on that address lists the tool names and says that the call arrives by POST.

In Cursor, add an MCP server with this URL and the header:

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

initialize and ping need no key. The protocol is 2025-03-26. A client that asks for 2024-11-05 gets that version. tools/list and tools/call need the key.

curl -X POST "https://heyreach.ch/api/mcp" \
  -H "Authorization: Bearer hr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_companies","arguments":{"canton":"ZH","industry_branch":"it","page_size":5}}}'

Shape of a tool result

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{ \"items\": [] }" }],
    "isError": false
  }
}

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. The JSON-RPC envelope itself stays successful.

Tools, same filters and costs as REST. The description is the German text the server returns:

  • search_companies — 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_company — 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_company — Dossier einer Firma freischalten. Kostet 1 Credit, ausser die Firma ist in diesem Workspace schon frei. Danach das volle Profil inklusive recherchierter Kontakte und hinterlegter Personen dieser Firma.
  • search_people — 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_person — 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_person — Kontaktdaten einer Person freischalten. Kostet 1 Credit, ausser sie ist in diesem Workspace schon frei. Liefert E-Mail, Telefon und LinkedIn, soweit vorhanden. Keine Garantie, dass eine Adresse hinterlegt oder geprüft ist.
  • list_unlocked_companies — Firmen, die dieser Workspace schon freigeschaltet hat. Kein erneuter Credit. Nützlich, bevor unlock_company noch einmal aufgerufen wird.
  • search_options — Erlaubte Filterwerte: Kantone, Hauptbranchen mit Unterbranchen, Rechtsformen, Mitarbeiterbänder, Alters-Presets, Herkunft, Sortierung und Credit-Kosten. Vor einer Branchensuche aufrufen, damit die ids stimmen.
  • account — Workspace und Credit-Stand dieses API-Schlüssels. Firmen- und Personenfreischaltung kosten je 1 Credit.

Errors

REST errors have this form. The HTTP status matches the case.

{
  "error": {
    "code": "bad_request",
    "message": "canton ist ein Kantonskürzel, zum Beispiel ZH, BE oder GE."
  }
}
Status and codeTypeRequiredMeaning
401 unauthorizedobjectalwaysKey is missing, wrong or revoked.
400 bad_requestobjectalwaysParameter unusable. message says which field.
404 not_foundobjectalwaysUID or person is not in the database.
402 insufficient_creditsobjectalwaysUnlock without balance. Nothing was opened.
429 rate_limitedobjectalwaysMore than 120 requests in one minute for this key.
500 errorobjectalwaysThe 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.

FAQ

Questions about the interface

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 applications and automations. MCP exposes the same endpoints as tools for assistants. Filters, fields and credits 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 HeyReach to my CRM?

Yes. Through the API you can integrate search, company profiles, people, unlocking and the balance into CRM systems, Make, internal tools or your own workflows.