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.
- Search, for example IT firms in Zurich with a website.
- Read the UID from the first hit. While it is locked you see available, not the email.
- 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_…"
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| q | string | no | Start 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. |
| canton | string | no | Canton code, for example ZH. A written-out name returns 400. |
| city | string | no | Place, substring. |
| postal_code | string | no | Four-digit postcode. |
| industry_branch | string | no | id of an industry group from GET /api/v1/options, for example immobilien or bau. |
| industry | string | no | Exact sub-industry label from the same list. Together with industry_branch, both must match. |
| legal_form | string | no | For example AG or GmbH. |
| employee_band | string | no | 1-10, 11-20, 21-50, 51-100, 101-250, 251+. An estimate. If revenue_band is also set, this band wins. |
| revenue_band | string | no | <0.5M, 0.5-2M, 2-10M, 10-50M, 50M+. Estimated from the employee band, not a reported turnover. |
| founded_from | number | no | Year, inclusive. |
| founded_to | number | no | Year, inclusive. |
| company_age | string | no | 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_website | string | no | yes or no. |
| unlock_status | string | no | unlocked or locked, for this workspace. |
| source | string | no | zefix (commercial register), google_local or web. |
| sort | string | no | name, city, founded, added. Default: founded. |
| page | number | no | From 1. Default 1. |
| page_size | number | no | 1 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_…"
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| uid | path | yes | With 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_…"
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| uid | path | yes | The 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_…"
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| q | string | no | Start of the registered name. “Hans” finds “Hans Meier”. “Meier” does not find that name. |
| role | string | no | Part of the role, for example Geschäftsführer. |
| canton | string | no | Canton code. |
| city | string | no | Place, substring. |
| uid | string | no | Company UID, with or without formatting. |
| sort | string | no | added, name, city, company. Default: added. |
| page | number | no | From 1. |
| page_size | number | no | 1 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_…"
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| id | path | yes | The 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_…"
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| id | path | yes | Person 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_…"
| Parameter | Type | Required | Meaning |
|---|---|---|---|
| page | number | no | From 1. |
| page_size | number | no | 1 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
| Field | Type | Required | Meaning |
|---|---|---|---|
| uid | string | always | Key in the database. |
| uid_formatted | string | always | Readable UID. |
| name | string | always | Company name. |
| legal_form | string | always | Legal form. |
| status | string | always | active or another register status. |
| canton | string | always | Canton code. |
| city | string | always | Place. |
| postal_code | string | always | Postcode. |
| founded_on | string | null | always | ISO date, when known. |
| industry | string | always | Industry on file. |
| employee_band | string | always | Estimated band, can be empty. |
| revenue_band_estimated | string | null | always | Estimated from the employee band. |
| unlocked | boolean | always | Whether this workspace has already opened the company. |
| has_website | boolean | always | Whether an own website is known. The address is not here. |
| brief | string | always | One sentence from founding, size and purpose. |
Company profile, beyond the hit
| Field | Type | Required | Meaning |
|---|---|---|---|
| purpose | string | always | Purpose from the register, when present. |
| street | string | always | Street. |
| legal_name | string | always | Registered name. |
| signals | array | always | Short facts. kind is web, hiring, demand, age or purpose. |
| available | object | only while locked | website, email, phone, people as yes/no. No values. |
| contact | object | only after unlock | website, email, phone, google_rating, google_rating_count. |
| people | array | only after unlock | name, role, city, and where present email, phone, linkedin_url. |
| insights | object | only after unlock | summary, revenue_estimate, hiring_signal, services, outreach_signals. |
| lage.trust | object | always | score and label. How reliable the classification is. |
| lage.peers | object | always | headline and detail. How the company sits in its industry. |
| lage.image | object | always | label and detail of the public image. |
| lage.demand | object | always | Search curve: state, verdict, label, detail, change_pct, topics, lines, months. |
| lage.supply | object | always | New incorporations in the industry, job roles and the FSO series for the sector. That describes the sector, not always the individual company. |
Person
| Field | Type | Required | Meaning |
|---|---|---|---|
| id | string | always | For GET and POST /people/{id}. |
| role | string | null | always | Role on the register. |
| company | object | always | uid, name, legal_form, city, canton, industry. |
| available | object | only while locked | email, phone, linkedin as yes/no. |
| contact | object | only after unlock | email, email_status, phone, linkedin_url. Empty means: not on file. |
| colleagues | number | only on GET of one person | People 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 code | Type | Required | Meaning |
|---|---|---|---|
| 401 unauthorized | object | always | Key is missing, wrong or revoked. |
| 400 bad_request | object | always | Parameter unusable. message says which field. |
| 404 not_found | object | always | UID or person is not in the database. |
| 402 insufficient_credits | object | always | Unlock without balance. Nothing was opened. |
| 429 rate_limited | object | always | More than 120 requests in one minute for this key. |
| 500 error | object | always | 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.
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.

