# Heermes API

Business data on people and companies, one call each.

- REST: `POST https://api.heermes.com/v1/<tool>` with `Authorization: Bearer <key>` and a JSON body.
- MCP: `https://heermes.com/api/mcp` (OAuth, or the same key as a bearer). The tools are the same.
- OpenAPI: `https://api.heermes.com/v1/openapi.json`.

Every tool takes one input as its body, or `inputs`: a list of up to 25 such bodies, each answered apart, in order. Keys given beside `inputs` are shared by all of them.

## Answers

```json
{"summary": "1 found for 1 input.", "data": {"results": []}, "usage": {"window_left": 0.92, "week_left": 0.98, "resets_at": "2026-01-01T15:00:00Z"}}
```

`usage` is on every answer: `window_left` and `week_left` are the share of the 5-hour window and of the 7-day ceiling still free, from 0 to 1, and `resets_at` is when room comes back. The allowance is counted in units; each tool says what it takes. A workspace without a plan has 100 free units, once: its `usage` is `{"plan": "free", "free_left": 0.62}`, and `find_phone` is not in them.

## Errors

```json
{"error": {"code": "WINDOW_SPENT", "message": "...", "resets_at": "2026-01-01T15:00:00Z", "retry_after_seconds": 1800}}
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `BAD_INPUT` | The body is not what the tool reads. The message says what to change. |
| 401 | `UNAUTHORIZED` | The key is missing or wrong. |
| 402 | `NO_PLAN` | The call needs a plan and the workspace has none: its free units are spent, or the tool is not in them. `checkout_url` says where to start one. |
| 403 | `NOT_IN_PRODUCT` | The key is not a Heermes key, or the tool is not a Heermes tool. |
| 404 | `NOT_FOUND` | No such tool, or no such job. |
| 429 | `WINDOW_SPENT` | The 5-hour window is spent. `Retry-After` and `resets_at` say when room comes back. |
| 429 | `WEEK_SPENT` | The 7-day ceiling is reached. `Retry-After` and `resets_at` say when room comes back. |
| 429 | `RATE_LIMITED` | Too many calls in a minute. |
| 503 | `SOURCE_DOWN` | The source could not be read. Nothing was taken; retry. |

## Tools

### find_email

Finds a person's verified work email from their name and their company's domain, or from their LinkedIn profile URL. Give linkedin_url, or full_name (or first_name and last_name) with company_domain; company (the company's name) works when the domain is unknown.

- Cost: 2 units for each verified email found. Nothing when none is found.
- Answer: data.results holds one entry for each input looked up, in order: {input, found, email: {address, status}}; status is verified, unverified or off_domain, and reason says why an entry is empty. data.done is false when the lookup is still running after about 50 seconds: read it later with job_get and data.job_id.

| Input | Type | |
| --- | --- | --- |
| `full_name` | string | The person's full name. |
| `first_name` | string |  |
| `last_name` | string |  |
| `company_domain` | string | The company's site, as acme.com. |
| `company` | string | The company's name, when its domain is unknown. |
| `linkedin_url` | string | The person's LinkedIn profile URL. |

```bash
curl -X POST https://api.heermes.com/v1/find_email -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"full_name":"Jane Doe","company_domain":"acme.com"}'
```

### find_phone

Finds a person's mobile number from their LinkedIn profile URL, or from their name and their company's domain.

- Cost: 25 units for each mobile found. Nothing when none is found. Needs a plan: mobiles are not in the free units.
- Answer: data.results holds one entry for each input looked up, in order: {input, found, mobile: {number}}; reason says why an entry is empty. data.done is false when the lookup is still running after about 50 seconds: read it later with job_get and data.job_id.

| Input | Type | |
| --- | --- | --- |
| `full_name` | string | The person's full name. |
| `first_name` | string |  |
| `last_name` | string |  |
| `company_domain` | string | The company's site, as acme.com. |
| `company` | string | The company's name, when its domain is unknown. |
| `linkedin_url` | string | The person's LinkedIn profile URL. The surest input for a mobile. |
| `email` | string | The person's email, when known. |

```bash
curl -X POST https://api.heermes.com/v1/find_phone -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"linkedin_url":"https://www.linkedin.com/in/jane-doe"}'
```

### find_linkedin

Finds a person's LinkedIn profile URL from their name and their company (its domain or its name).

- Cost: 1 unit for each profile found. Nothing when none is found.
- Answer: data.results holds one entry for each input looked up, in order: {input, found, linkedin: {url, title, company}}; reason says why an entry is empty. data.done is false when the lookup is still running after about 50 seconds: read it later with job_get and data.job_id.

| Input | Type | |
| --- | --- | --- |
| `full_name` | string | The person's full name. |
| `first_name` | string |  |
| `last_name` | string |  |
| `company_domain` | string | The company's site, as acme.com. |
| `company` | string | The company's name. |
| `email` | string | The person's email, when known. |

```bash
curl -X POST https://api.heermes.com/v1/find_linkedin -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"full_name":"Jane Doe","company":"Acme"}'
```

### linkedin_profile

Reads one person's LinkedIn profile: name, headline, location, current and past positions with their dates.

- Cost: 1 unit a profile. Nothing when the profile does not exist.
- Answer: data.results holds the profile (an empty list when it does not exist).

| Input | Type | |
| --- | --- | --- |
| `url` | string | Required. The profile's URL, as https://www.linkedin.com/in/jane-doe. |

```bash
curl -X POST https://api.heermes.com/v1/linkedin_profile -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"url":"https://www.linkedin.com/in/jane-doe"}'
```

### linkedin_company

Reads one company's LinkedIn page: name, description, industry, headcount, website, headquarters.

- Cost: 1 unit a page. Nothing when the page does not exist.
- Answer: data.results holds the page (an empty list when it does not exist).

| Input | Type | |
| --- | --- | --- |
| `url` | string | Required. The page's URL, as https://www.linkedin.com/company/acme. |

```bash
curl -X POST https://api.heermes.com/v1/linkedin_company -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"url":"https://www.linkedin.com/company/acme"}'
```

### search_people

Searches people by current job title, company, place and keywords. Answers up to 25 people a page, each with name, title, company, place and LinkedIn URL.

- Cost: 1 unit a page of results, 2 at most. Nothing for an empty page.
- Answer: data.results holds the people; data.next holds the cursor of the next page, or null.

| Input | Type | |
| --- | --- | --- |
| `title` | string | The current job title, as Head of Sales. |
| `company` | string | The current company's name. |
| `location` | string | A city, a region or a country. |
| `keywords` | string | Words the profile must hold. |
| `limit` | integer |  |
| `cursor` | string | data.next.cursor of the page before, for the next page. |

```bash
curl -X POST https://api.heermes.com/v1/search_people -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"title":"Head of Sales","location":"Berlin"}'
```

### search_companies

Searches companies by activity keywords and place, on LinkedIn. With country "FR", or any of naf, departments, postal_codes, min_employees and max_employees, it searches France's national register instead: legal name, registration number, activity code, headcount band, address, revenue and officers.

- Cost: 1 unit a page of LinkedIn results, nothing for an empty page. France's register is free.
- Answer: data.results holds the companies; data.next holds the cursor or the page of the next page, or null.

| Input | Type | |
| --- | --- | --- |
| `keywords` | string | What the company does, or its name. |
| `location` | string | A city, a region or a country (LinkedIn search). |
| `country` | string | "FR" searches France's national register. |
| `naf` | array | France: activity codes, as 62.02A. |
| `departments` | array | France: department numbers, as 75. |
| `postal_codes` | array | France: postal codes. |
| `min_employees` | integer | France: the smallest headcount. |
| `max_employees` | integer | France: the largest headcount. |
| `limit` | integer | France: results a page. |
| `page` | integer | France: the page to read, from data.next.page. |
| `cursor` | string | LinkedIn: data.next.cursor of the page before. |

```bash
curl -X POST https://api.heermes.com/v1/search_companies -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"keywords":"industrial robotics","location":"Munich"}'
```

### company_signals

Reads dated facts about one company: hiring (its job ads on French job boards), funding (its rounds, with date, amount and investors), news (recent press) and contracts (public contracts awarded to it in France, Belgium, Luxembourg and Switzerland). Give company (its name), domain, or both; kinds limits the read to some of the four.

- Cost: hiring and contracts are free. news takes 1 unit for every 10 companies. funding takes 3 units a company, with or without a round, and needs domain.
- Answer: data.results holds one entry for each company: {input, hiring, funding, news, contracts}, each a list of dated facts, and errors naming the signals that could not be read.

| Input | Type | |
| --- | --- | --- |
| `company` | string | The company's name. |
| `domain` | string | The company's site, as acme.com. Needed for funding. |
| `kinds` | array | Which signals to read. All four by default. |
| `since_days` | integer | How far back job ads are read, in days. 30 by default. |

```bash
curl -X POST https://api.heermes.com/v1/company_signals -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"company":"Acme","domain":"acme.com","kinds":["hiring","funding"]}'
```

### web_search

Searches the web and answers the results' titles, links and snippets.

- Cost: 1 unit a search.
- Answer: data.results holds the results in the search's order.

| Input | Type | |
| --- | --- | --- |
| `query` | string | Required. What to search for. |
| `country` | string | A two-letter country code, as us. us by default. |
| `language` | string | A two-letter language code, as en. en by default. |
| `limit` | integer |  |

```bash
curl -X POST https://api.heermes.com/v1/web_search -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"query":"acme series b funding"}'
```

### web_read

Reads one web page and answers its text.

- Cost: 1 unit for every 10 pages read.
- Answer: data.results holds the page: {url, title, text}.

| Input | Type | |
| --- | --- | --- |
| `url` | string | Required. The page's address, starting with http:// or https://. |

```bash
curl -X POST https://api.heermes.com/v1/web_read -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"url":"https://acme.com/about"}'
```

### verify_email

Checks whether an email address can receive mail. status is verified, catch_all (the domain accepts every address), risky, invalid or unknown; with company_domain, an address on another organisation's domain answers off_domain at no cost.

- Cost: 1 unit an address checked.
- Answer: data.results holds one entry for each address, in order: {email, status, score}.

| Input | Type | |
| --- | --- | --- |
| `email` | string | Required. The address to check. |
| `company_domain` | string | The company's site, to tell an address that is not the company's. |

```bash
curl -X POST https://api.heermes.com/v1/verify_email -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"email":"jane.doe@acme.com"}'
```

### usage

Says what is left of the allowance: the share of the 5-hour window and of the 7-day ceiling still free (0 to 1), and when room comes back. Without a plan: the free units spent and their limit.

- Cost: Free.
- Answer: data holds plan, window: {left, resets_at} and week: {left, resets_at}; without a plan, plan is free and data holds free: {used, limit}.

```bash
curl -X POST https://api.heermes.com/v1/usage -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{}'
```

### job_get

Reads a find_email, find_phone or find_linkedin lookup that was still running when its tool answered, by the job_id that answer gave.

- Cost: Free.
- Answer: The same data as the find: results, done, and job_id while it runs.

| Input | Type | |
| --- | --- | --- |
| `job_id` | string | Required. data.job_id of the find that was still running. |

```bash
curl -X POST https://api.heermes.com/v1/job_get -H "Authorization: Bearer $HEERMES_KEY" -H "Content-Type: application/json" -d '{"job_id":"8c0f6c0e-5a5b-4a39-9a2f-2f6f3b1c7d10"}'
```
