# Moleman API

> Find business emails and check that they work; search businesses in an area; write company summaries. REST + JSON, Bearer API keys (mm_live_ real, mm_test_ made-up and free). You pay only for emails that work.

- Base URL: https://moleman.io/api/v1
- OpenAPI 3.1: https://moleman.io/api/v1/openapi.json
- All docs in one file: https://moleman.io/api/v1/docs.md

## Get started

- [Moleman API](https://moleman.io/docs/index.md): What the API does, what it costs, where to start.
- [Quickstart](https://moleman.io/docs/quickstart.md): Your first working email in 3 calls (curl, Node, Python).
- [API keys](https://moleman.io/docs/authentication.md): Live and test keys, revoking, 401/403.
- [Test mode](https://moleman.io/docs/test-mode.md): Test keys: made-up results, never charged; test values.

## Guides

- [Credits](https://moleman.io/docs/credits.md): What costs credits, what is free (incl. 30-day reuse), holds.
- [Jobs & webhooks](https://moleman.io/docs/webhooks.md): Polling, webhooks, signature check in Node and Python, retries.
- [Rate limits](https://moleman.io/docs/rate-limits.md): Limits, X-RateLimit headers, 429 and Retry-After.
- [Idempotency](https://moleman.io/docs/idempotency.md): Idempotency-Key: retry safely, never pay twice.
- [Pages & CSV](https://moleman.io/docs/pagination.md): Cursor pages and CSV.
- [Errors](https://moleman.io/docs/errors.md): The error format and every error code.
- [Data rules](https://moleman.io/docs/data-rules.md): Opt-outs, deletion, 30 days, owner names, US state rules.
- [Versions & changelog](https://moleman.io/docs/versioning.md): What may change in v1, and what changed.

## Integrations

- [Clay](https://moleman.io/docs/clay.md): Moleman as a Clay HTTP API column.
- [Make, Zapier, n8n](https://moleman.io/docs/no-code.md): HTTP steps and webhook triggers.
- [Instantly & Smartlead](https://moleman.io/docs/csv-export.md): CSV export that imports without mapping work.

## API reference

- [Your credits, plan and rate limit](https://moleman.io/docs/api/account.md): GET /api/v1/account
- [Find emails for people or businesses](https://moleman.io/docs/api/find-contacts.md): POST /api/v1/find-contacts
- [Check if emails work](https://moleman.io/docs/api/verify.md): POST /api/v1/verify
- [Company summary and first line](https://moleman.io/docs/api/deep-search.md): POST /api/v1/deep-search
- [Find businesses in an area, with emails](https://moleman.io/docs/api/search.md): POST /api/v1/search
- [Your jobs, newest first](https://moleman.io/docs/api/jobs-list.md): GET /api/v1/jobs
- [A job's status and results](https://moleman.io/docs/api/jobs-get.md): GET /api/v1/jobs/{id}
- [Stop a job](https://moleman.io/docs/api/jobs-cancel.md): POST /api/v1/jobs/{id}/cancel
- [Upload a list](https://moleman.io/docs/api/lists-create.md): POST /api/v1/lists
- [Your lists, newest first](https://moleman.io/docs/api/lists-list.md): GET /api/v1/lists
- [A list with its results](https://moleman.io/docs/api/lists-get.md): GET /api/v1/lists/{id}
- [Rows as JSON pages or one CSV file](https://moleman.io/docs/api/lists-rows.md): GET /api/v1/lists/{id}/rows
- [Delete a list](https://moleman.io/docs/api/lists-delete.md): DELETE /api/v1/lists/{id}
- [Send a signed test event](https://moleman.io/docs/api/webhooks-test.md): POST /api/v1/webhooks/test
- [This API as OpenAPI 3.1](https://moleman.io/docs/api/openapi.md): GET /api/v1/openapi.json
- [All docs as one Markdown file](https://moleman.io/docs/api/docs-md.md): GET /api/v1/docs.md
- [Clay HTTP API column settings](https://moleman.io/docs/api/clay-template.md): GET /api/v1/clay-template.json