# Evaboot API

> Complete documentation for Large Language Models


---

## Document: Troubleshooting

Common API errors and how to resolve them.

URL: /troubleshooting


# Troubleshooting

## Check your connection first

Before debugging anything else, call the quota endpoint. It needs nothing but
your API key, so it tells you whether the key works and whether your account is
properly set up:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.evaboot.com/v1/quota/
```

## Errors

Every error comes back in the same shape:

```json
{
  "success": false,
  "error": { "type": "InsufficientCredits", "message": "..." }
}
```

### 401 Unauthorized

- Check the header is exactly `Authorization: Bearer YOUR_API_KEY`.
- Confirm the key is current — rotating or deleting it in **Integrations → API**
  invalidates the old value immediately.

### 402 Insufficient credits

Your balance won't cover the request. Check it with `GET /v1/quota/` or on the
dashboard.

### 429 Too many requests

Either your daily export quota is spent, or you've hit the search-builder's cap
of 100 calls per day. Quotas reset daily.

### 422 Validation error

The request body or a Sales Navigator URL was rejected. The `message` names the
specific field or reason. A URL that LinkedIn itself refuses — a search that's
too broad, or filters that exceed its limits — also surfaces here.

## Quota shows 0, or a seat is invalid

Your Evaboot account has no usable Sales Navigator cookies. The stored session
is missing, or LinkedIn no longer accepts it.

Evaboot cannot refresh those cookies. Sign in to this same Evaboot account in
Chrome, open a Sales Navigator search with the Evaboot extension installed, and
click **Export with Evaboot**. Opening the Launch export page writes the cookies. The user does not have to click Launch export. Installing
the extension, or opening Sales Navigator, does not by itself. Then retry.

Steps: https://help.evaboot.com/public/bug-fixing/how-to-reconnect-your-linkedin-account/

## 409, connection expired

The API answers 409 when the Sales Navigator seat was never connected, and again
when the cookies it stored are no longer accepted. Both messages name the same
fix: the **Export with Evaboot** click above. A reconnect is a new export, not
a reinstall.

## Still stuck?

Contact us via the [Help Center](https://help.evaboot.com/). Include the
endpoint, the request body, and the full error response.



---

## Document: MCP Server

Connect Evaboot to Claude, ChatGPT, Gemini, Cursor, or any MCP client.

URL: /mcp-server


# MCP Server

Connect Evaboot to Claude, ChatGPT, Gemini, Cursor, or any MCP-compatible client. Your
assistant can then build Sales Navigator searches, launch exports, and find or
validate emails on your behalf.

Nothing to install — the server is hosted.

**Server URL:** `https://mcp.evaboot.com/mcp`

## Which connection method do I use?

| Method | Use it for | How you sign in |
| --- | --- | --- |
| **Browser sign-in (OAuth)** | claude.ai, Claude Desktop, Claude Cowork, ChatGPT, Manus, Gemini | Click through an Evaboot login + consent screen. No API key needed. |
| **API key** | Claude Code, Cursor, VS Code, scripts | Paste your Evaboot API key into a config file. |

Web chat UIs (claude.ai, ChatGPT, Gemini) can't send custom headers, so they use OAuth.
Config-file clients can use either, but the API key is simpler.

Both methods give access to the same tools and draw on the same credit balance.

## Connect with browser sign-in (OAuth)

### claude.ai, Claude Desktop, and Claude Cowork

Remote connectors are attached to your Claude account, so adding it once covers
web, desktop, and Cowork. In a Cowork session, enable Evaboot from the + menu.

1. In Claude, go to **Customize → Connectors**.
2. Click **+**, then **Add custom connector**.
3. Enter the URL `https://mcp.evaboot.com/mcp` and click **Add**.
4. Click **Connect**. A browser window opens on Evaboot.
5. Sign in to your Evaboot account if you aren't already.
6. On the **Authorize** screen, confirm access and click **Authorize**.

Claude returns to the connector list showing Evaboot as connected. Leave the
Advanced/OAuth credential fields empty — the server registers Claude
automatically.

Free Claude plans allow one custom connector; paid plans allow several. On
Team/Enterprise an owner adds the connector in **Organization settings →
Connectors** and members then click **Connect**.

### ChatGPT

Custom connectors require developer mode, available on Pro, Plus, Business,
Enterprise and Education plans, on the web.

1. Go to **Settings → Apps → Advanced settings** and turn on **Developer mode**.
2. In the **Connectors** panel, click **Add custom connector**.
3. Enter `https://mcp.evaboot.com/mcp`. Leave authentication as OAuth.
4. Complete the Evaboot sign-in and consent screen.
5. The connector appears under **Drafts**, then in the composer's Developer Mode
   tool picker — enable Evaboot for the conversation you want to use it in.

On Business/Enterprise workspaces an admin may first need to allow developer
mode under **Workspace Settings → Permissions & Roles → Connected Data**.

If the server's tools change later, hit **Refresh** on the connector's settings
page.

### Manus

1. In Manus, go to **Settings → Connectors**.
2. Click **Add connectors**, then **Custom MCP**, then **Direct configuration**.
3. Enter `https://mcp.evaboot.com/mcp`. Leave authentication empty.
4. Complete the Evaboot sign-in and consent screen.
5. Enable Evaboot in the task you want to use it in.

### Gemini

The Gemini app takes custom MCP servers as custom apps. For now this needs a
personal Google account, in English, with Keep Activity on, and it is available
in the US. A work or school account cannot add one. Once connected, the app is
available on the web and in the mobile app.

1. Open [Connected Apps](https://gemini.google.com/apps).
2. Under **Custom apps**, add a custom app.
3. Enter `https://mcp.evaboot.com/mcp`. Leave advanced credentials empty. The
   server registers itself.
4. Complete the Evaboot sign-in and consent screen.
5. In a chat, type `@` and choose Evaboot.

## Connect with an API key

Find your key in the Evaboot dashboard under **Integrations → API**. If you don't
have one yet, click **Refresh** to generate it. The same panel lets you rotate or
delete a key — both immediately break any integration still using the old value.

Your API key is a long-lived secret with full access to your Evaboot account.
Treat it like a password and never commit it to a repository.

### Claude Code

```sh
claude mcp add --transport http evaboot https://mcp.evaboot.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

Then run `/mcp` inside Claude Code to confirm Evaboot is connected.

You can also omit `--header` and let Claude Code run the OAuth flow instead:

```sh
claude mcp add --transport http evaboot https://mcp.evaboot.com/mcp
```

### Cursor

Create `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "evaboot": {
      "url": "https://mcp.evaboot.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

### VS Code (Copilot)

Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "evaboot": {
      "type": "http",
      "url": "https://mcp.evaboot.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Restart the client after editing any config file.

## Available tools

Every tool the hosted server exposes is listed below. Your client also shows
each tool's full description in its tool list.

### Search building

| Tool | What it does | Credits |
| --- | --- | --- |
| `build_sn_search_from_prompt` | Turns a natural-language audience into a validated Sales Navigator URL using Evaboot's search agent. Resolves industries, titles and company names against LinkedIn's real filter catalog. | Free |
| `get_account_based_search_job` | Polls an account-based lead search started by `build_sn_search_from_prompt`. | Free |
| `cancel_sales_nav_job` | Stops an account-based search, a list-from-search run, or a split. Lists already saved are kept. A running job is flagged and stops before its next list write, so keep polling until it ends. Does not stop an export or an email job. | Free |

`build_sn_search_from_prompt` may run an account-based lead search (company-first: it builds
the company set first, then filters leads by it), which takes several minutes
and creates account lists in your own LinkedIn account. Poll
`get_account_based_search_job` for progress.

### Exporting a list category

Ask, for example: “Export my Recently Accepted Connections list, but only people
who changed jobs in the past 90 days.” The assistant looks up the list by name
and exports it with `list_category="changed_jobs"`. If names are ambiguous,
it asks which list you mean.

`changed_jobs` selects leads who changed jobs in the past 90 days.
`posted_on_linkedin` selects leads who posted on LinkedIn in the past 30 days.
Both categories are supported on lead lists. `all` selects a whole lead or account
list. Omit `list_category` to keep a supported filter already present in the URL.
Other category tabs are not yet supported. Unknown filters or conflicts between
the URL and category are rejected before an export starts; the assistant must
not retry by dropping the filter. A connected Sales Navigator account is required.

### Extracting leads

| Tool | What it does | Credits |
| --- | --- | --- |
| `export_sn_search_or_list` | Starts an export from a Sales Navigator search or list URL. Asynchronous — returns an `extraction_id`. `max_results` keeps only the first N results LinkedIn serves; quota is checked against N. | 1 per lead, email included |
| `export_profile_list` | Bulk export from a list of profile URLs or ids (1–2500). Asynchronous. | 1 per lead, email included |
| `export_profile` | Extracts one profile and returns it immediately. | 1, email included |
| `get_export` | Fetches an export's status, progress, and results. | Free |
| `get_export_list` | Lists your exports, newest first. | Free |

Every export finds a verified email for each lead where one exists. The
`enrich_email` argument is still accepted but ignored. An export that already
finished cannot be enriched afterwards.

### Recurring exports

| Tool | What it does | Credits |
| --- | --- | --- |
| `create_recurring_export` | Repeats a Sales Navigator search daily, weekly or monthly, from an existing export or a search URL. A URL that already has a saved search id is not saved again. The first run is one interval later and includes only new leads. A second call for the same search updates the cadence. | 1 per lead, each run |
| `list_recurring_exports` | Lists your recurring exports, paused ones included. | Free |
| `get_recurring_export` | Fetches one recurring export. | Free |
| `update_recurring_export` | Renames, changes the cadence, or pauses and resumes a recurring export. | Free |
| `delete_recurring_export` | Stops a recurring export permanently. Exports already produced stay. | Free |

Each run uses your connected Sales Navigator account and counts against daily
quota. A run with no credits or no connected account is skipped, and the next
date still moves forward.

### Lead lists

These tools act on the lists in your own Sales Navigator account.

| Tool | What it does | Credits |
| --- | --- | --- |
| `list_lead_lists` | Lists your lead lists. | Free |
| `create_lead_list` | Creates an empty lead list. | Free |
| `add_leads_to_list` | Adds up to 999 leads to an existing list. | Free |
| `create_lead_list_from_ids` | Creates lead lists from profile ids, splitting at 999 per list. | Free |
| `create_lead_list_from_search` | Runs a lead search and saves every result into a new list. Asynchronous. | Free |
| `split_lead_search` | Splits a lead search of more than 2,500 people into list-backed slices you can export one by one. Asynchronous. | Free |
| `delete_lead_list` | Deletes a lead list. | Free |

### Account lists

| Tool | What it does | Credits |
| --- | --- | --- |
| `list_account_lists` | Lists your company lists. | Free |
| `create_account_list` | Creates an empty company list. | Free |
| `add_accounts_to_list` | Adds up to 999 companies to an existing list. | Free |
| `create_account_list_from_ids` | Creates a company list from company ids. | Free |
| `create_account_list_from_search` | Runs a company search and saves every result into a new list. Asynchronous. | Free |
| `split_account_search` | Splits a company search of more than 1,000 companies into list-backed slices. Asynchronous. | Free |
| `delete_account_list` | Deletes a company list. | Free |

| Tool | What it does | Credits |
| --- | --- | --- |
| `get_list_from_search_status` | Polls a list-from-search or split run. | Free |

Stop one with `cancel_sales_nav_job`.

### Search pages

| Tool | What it does | Credits |
| --- | --- | --- |
| `search_sn_leads` | Reads one page of a lead search URL, with each lead's profile urn for the list tools. | Free |
| `search_sn_accounts` | Reads one page of a company search URL, with each company's id for the list tools. | Free |

### Saved searches

| Tool | What it does | Credits |
| --- | --- | --- |
| `list_saved_searches` | Lists your saved lead or company searches. | Free |
| `save_search` | Saves a Sales Navigator search on your seat. | Free |
| `delete_saved_search` | Deletes a saved search. | Free |

### Alerts

| Tool | What it does | Credits |
| --- | --- | --- |
| `read_alerts` | Reads your Sales Navigator alerts: job changes, posts, funding rounds. | Free |

### Integrations

| Tool | What it does | Credits |
| --- | --- | --- |
| `list_integrations` | Lists the CRM and webhook destinations connected to your account. No secrets are returned. | Free |
| `connect_integration` | Connects Clay, Make, Zapier, n8n or a custom webhook from its https URL, or starts a HubSpot connection. `auto` chooses between pushing every finished export and pushing only on request. | Free |
| `push_export` | Sends one finished export to one connected destination. | Free |
| `test_integration` | Sends a sample payload to a webhook destination. | Free |

For HubSpot, where it is enabled on your account, the first call returns a
link to approve access. Call `connect_integration` again after approving. It
returns the destination, or a mapping page link when a field still has to be
chosen.

### Finding emails

| Tool | What it does | Credits |
| --- | --- | --- |
| `find_email_single` | Finds one email from a name + company. Immediate. | 1 |
| `find_emails` | Bulk email-finder job. Asynchronous. | 1 per email found |
| `get_email_finder_job` | Fetches a job's status and results. | Free |
| `list_email_finder_jobs` | Lists your email-finder jobs. | Free |

### Verifying emails

| Tool | What it does | Credits |
| --- | --- | --- |
| `verify_email_single` | Verifies one address. Immediate. | 1 |
| `verify_email` | Bulk verification job. Asynchronous. | 1 per email checked |
| `get_email_verification_job` | Fetches a job's status and results. | Free |
| `list_email_verification_jobs` | Lists your verification jobs. | Free |

### Account

| Tool | What it does | Credits |
| --- | --- | --- |
| `get_daily_export_quota` | Your remaining daily export quota and credit balance. | Free |
| `verify_token` | Checks that the configured API key is valid. | Free |

## Costs and limits

- Exports and email lookups consume **credits** from your Evaboot balance. For
  exports the credits are checked when you launch and charged when the export
  completes, based on the number of leads actually found.
- Exports also consume **daily quota**, tied to your connected Sales Navigator
  seat. Call `get_daily_export_quota` before a large run.
- If you have no connected Sales Navigator account your quota is 0. Sign in to
  this same Evaboot account in Chrome, open a Sales Navigator search with the
  Evaboot extension installed, and click **Export with Evaboot**. Opening the
  Launch export page writes the cookies. The user does not have to click
  Launch export. Installing the extension or opening Sales Navigator does
  not, by itself.

## Example

> "Find marketing directors at French SaaS companies with 50–200 employees, then
> export the first 50 with emails."

The assistant calls `build_sn_search_from_prompt` to produce the search URL, then
`export_sn_search_or_list`, then polls `get_export` until the results, emails
included, are ready.

## Troubleshooting

**Connection fails, or the client reports 401.**
On the API-key path, check the header is exactly
`Authorization: Bearer <key>` and the key is current. On the OAuth path,
disconnect and reconnect to redo the consent flow.

**Tools return "insufficient credits" (402).**
Check your balance with `get_daily_export_quota` or in the Evaboot dashboard.

**Tools return a quota error (429).**
You've hit your daily export limit for the Sales Navigator seat, or
`build_sn_search_from_prompt`'s daily cap. Wait for the daily reset.

**Quota shows 0, or a tool returns 409.**
The LinkedIn cookies are missing or no longer accepted. Evaboot cannot refresh
them. Sign in to this same Evaboot account in Chrome, open a Sales Navigator
search with the Evaboot extension installed, and click **Export with Evaboot**.
Opening the Launch export page writes the cookies. The user does not have to
click Launch export. Installing the extension or opening Sales Navigator does
not, by itself. Then retry. If the extension cannot refresh the session, copy
`li_a` and `li_at` from Chrome DevTools into Settings in the Evaboot app.
Never paste them into the assistant.
Steps: https://help.evaboot.com/public/bug-fixing/how-to-reconnect-your-linkedin-account/

**The client shows no tools after connecting.**
Refresh the connector's tool list (ChatGPT has an explicit **Refresh** button),
or remove and re-add the server.



---

## Document: Evaboot API

Find email addresses and extract prospect data programmatically.

URL: /


# Evaboot API

The Evaboot API is a JSON REST API that lets you extract prospects from LinkedIn
Sales Navigator and find or validate their professional email addresses.

## Quick start

Get your API key from the Evaboot dashboard under **Integrations → API**. If the
field is empty, click **Refresh** to generate one.

All requests take an `Authorization` header:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.evaboot.com/v1/quota/
```

That call returns your credit balance and remaining daily quota, so it doubles as
a way to check your key works.

### Find an email

```bash
curl -X POST https://api.evaboot.com/v1/email-finder/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prospects": [
      {
        "first_name": "John",
        "last_name": "Doe",
        "company_name": "Example Corp",
        "company_domain": "example.com"
      }
    ]
  }'
```

This returns a `job_id` immediately. Poll `GET /v1/email-finder/{job_id}/` for
results — it answers `202` while the job runs and `200` once it's done.

## What you can do

- **Extract from Sales Navigator** — turn a search or list URL into structured
  prospect data.
- **Find emails** — one prospect at a time, or thousands in a bulk job.
- **Validate emails** — check deliverability before you send.
- **Build searches** — describe an audience in plain language and get a Sales
  Navigator URL back.
- **Receive webhooks** — get a callback when a long-running job finishes.

## Costs

Extractions and email lookups draw on your Evaboot credit balance: 1 credit per
lead extracted with its verified email included (every lead extraction finds
emails), 1 per email found by the email finder, and 1 per email validated.
Search building is free. Check `GET /v1/quota/` before a large run.

## Support

- [Help Center](https://help.evaboot.com/)
- [YouTube](https://www.youtube.com/@JBEvaboot)