# Moleman API

The Moleman API finds business emails and checks that they work. Everything you can do in the app, you can do with a few HTTP calls: from your own scripts, Clay, Make, Zapier or n8n.

**Base URL:** `https://moleman.io/api/v1` · **Auth:** `Authorization: Bearer <your key>` · **Format:** JSON in, JSON out (CSV for exports)

## What you can do

| You want | Call | Costs |
| --- | --- | --- |
| The email of a person at a business | [`POST /find-contacts`](/docs/api/find-contacts) | 1 credit per email that works |
| The business email (info@, office@ …) or the owner | [`POST /find-contacts`](/docs/api/find-contacts) with `action` | 1 credit per email that works |
| Check emails you already have | [`POST /verify`](/docs/api/verify) | 0.1 credit per email that works |
| Businesses in an area, with emails | [`POST /search`](/docs/api/search) | 1 credit per email that works |
| A company summary and a first line | [`POST /deep-search`](/docs/api/deep-search) | 0.5 credit per summary |
| Your credits, plan and limits | [`GET /account`](/docs/api/account) | free |

You only pay for results: an email that does not work, or that we could not confirm, costs nothing. Anything your account already got in the last 30 days is answered again for free. See [Credits](/docs/credits).

## Start here

1. Open the [API page in the app](https://moleman.io/app/api) and create a **test key** (`mm_test_…`). It returns made-up results and never costs anything.
2. Run the [Quickstart](/docs/quickstart): three calls, and you have your first working email.
3. When it works, create a **live key** (`mm_live_…`) and use real data.

## How it works

Every request that finds or checks emails starts a **job**. Small jobs finish in seconds: send `"wait": 30` and the answer already has the results. Big jobs (up to 50,000 rows) run in the background: poll [`GET /jobs/{id}`](/docs/api/jobs-get) or let us call your [webhook](/docs/webhooks) when they are done.

Results use the same words as the app: **Works**, **Probably works**, **Not sure**, **On hold**, **Still checking…** Only "Works" is charged.

## For AI agents and tools

- [OpenAPI 3.1](https://moleman.io/api/v1/openapi.json) – generated from the same schemas the server checks requests with
- [All docs as one Markdown file](https://moleman.io/api/v1/docs.md)
- [llms.txt](https://moleman.io/llms.txt)