Guides

Versions & changelog

The API version is part of the path: /api/v1. Within v1:

• We add things (new endpoints, new fields, new error codes, new event types) without warning. Ignore fields you do not know.
• We never remove or rename a field, change its type or change what a status word means within v1.
• A breaking change gets a new version (/api/v2), announced by email at least 90 days before v1 changes.

The current schema version is 2026-11-05 (in openapi.json and in every webhook as apiVersion).

Changelog

2026-11-05

• New: test keys (mm_test_…) with made-up results; GET /account; GET /jobs, POST /jobs/{id}/cancel, GET /lists, GET /lists/{id}/rows (JSON pages or CSV), DELETE /lists/{id}, POST /webhooks/test; wait on POSTs; Idempotency-Key on every POST; X-RateLimit-* headers; cursor pages; role: "best" on search.
• New fields on every result: result, resultCode, resultMeaning and the status words (emailStatusText, findStatusText, emailTypeText) – the same words as the app.
• Changed: errors are now { "error": { "code", "message", "docs_url" } } (before: { "error": "text" }).
• Changed: webhooks are signed as X-Moleman-Signature: t=…,v1=… over <t>.<body> with your account signing secret (before: sha256=… over the body, only with webhookSecret), and retried 8 times.
• Changed: find-contacts and verify results no longer carry company-register fields (they stay in deep-search).
• Changed: GET /jobs/{id} returns the job's own rows (before: the whole list), up to 1,000 per page.

2026-10-31

• First version: search, find-contacts, verify, deep-search, jobs, lists, webhooks.