Verify from your code. Or your agent.

Quickstart

Base URL https://www.zenverifier.com/api/v1. JSON in, JSON out, HTTPS only.

1. Create a key. In the dashboard, open API & MCP in the sidebar and create a key. Owners and admins can do this. The Server integration — verify + lists preset covers everything below. The key is shown once, so put it straight into your secret store.
2. Verify an address.
   curlNode.jsPython

   Copy

   bash

   export ZV_API_KEY="zv_live_YOUR_KEY"
   
   curl -X POST https://www.zenverifier.com/api/v1/verify \
     -H "Authorization: Bearer $ZV_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"email":"jane@example.com"}'

3. Read the answer. Act on result: keep ok, decide on catch_all, drop invalid and disposable, try unknown again later.
   200 OK · application/jsonCopy

   {
     "data": {
       "id": 48213,
       "email": "jane@example.com",
       "result": "ok",
       "quality": "good",
       "subresult": "ok",
       "free": false,
       "role": false,
       "didYouMean": null,
       "cached": false,
       "charged": 1,
       "creditsBalance": 24179,
       "verifiedAt": "2026-10-12T09:41:07.000Z"
     }
   }

Authentication

Every request carries an API key in the Authorization header:

Authorization: Bearer zv_live_YOUR_KEY

• A key belongs to one workspace and sees only that workspace’s lists, history and credits.
• Keys start with zv_live_ and are shown once, when created. We store only a SHA-256 hash, so a lost key can’t be recovered: roll it or create a new one.
• Send keys only in the Authorization header, never in a URL or query string. The API has no CORS support on purpose: call it from your servers, not from a browser.
• If the person who created a key leaves the workspace, the key stops working.
• Owners and admins get an email whenever a key is created, rolled or revoked. The email shows the key’s prefix (zv_live_ab12), never the key.

Scopes

A key can only do what its scopes allow. read:* covers every …:read scope and * covers everything. Write scopes don’t include the matching read scope.

Presets

The dashboard creates keys from these presets. The first one is the default. The last column shows which MCP tools a key made from the preset can use.

Expiry, rolling and revoking

• Keys expire never, or after 30, 90 or 365 days. Owners and admins get an email 7 days before a key expires.
• Roll issues a new key with the same name, scopes and expiry. The old key keeps working for 24 more hours and then stops, so you can swap keys without downtime.
• Revoke stops a key immediately, including a rolled key that’s still in its 24-hour grace period.

Credits & caching

The API and MCP spend the same credits as the dashboard, under the same rules.

Check your balance any time with GET /api/v1/account.

Endpoints

Single objects come back as { "data": … }. Collections are paginated by page number and add a pagination object. Every response carries Cache-Control: no-store. Responses to authenticated requests also carry the rate-limit headers (401 and 403 don’t).

{
  "data": [
    "…"
  ],
  "pagination": {
    "page": 2,
    "pageSize": 25,
    "totalPages": 7,
    "total": 161
  }
}

curl https://www.zenverifier.com/api/v1/account \
  -H "Authorization: Bearer $ZV_API_KEY"

curl -X POST https://www.zenverifier.com/api/v1/verify \
  -H "Authorization: Bearer $ZV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com"}'

curl "https://www.zenverifier.com/api/v1/verifications?email=jane@example.com" \
  -H "Authorization: Bearer $ZV_API_KEY"

curl "https://www.zenverifier.com/api/v1/lists?status=finished" \
  -H "Authorization: Bearer $ZV_API_KEY"

curl -X POST https://www.zenverifier.com/api/v1/lists \
  -H "Authorization: Bearer $ZV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: october-signups-2026-10-12" \
  -d '{"name":"October signups","emails":["jane@example.com","sales@example.org"]}'

# or upload a file
curl -X POST https://www.zenverifier.com/api/v1/lists \
  -H "Authorization: Bearer $ZV_API_KEY" \
  -F "file=@signups.csv" \
  -F "name=October signups"

curl https://www.zenverifier.com/api/v1/lists/1207 \
  -H "Authorization: Bearer $ZV_API_KEY"

curl "https://www.zenverifier.com/api/v1/lists/1207/results?result=ok,catch_all&pageSize=500" \
  -H "Authorization: Bearer $ZV_API_KEY"

curl -o october-clean.csv \
  "https://www.zenverifier.com/api/v1/lists/1207/download?filter=ok_and_catch_all" \
  -H "Authorization: Bearer $ZV_API_KEY"

Verification fields

List fields

Result values

Every verification and every list row has one result. List counts use the same five buckets (catch_all is catchAll there).

Bulk lists

Lists run in the background. Up to 50,000 unique emails per list over the API (5,000 over MCP); split anything bigger.

1. Submit with POST /api/v1/lists, as JSON or a file upload. Send an Idempotency-Key so a retry can’t create (and charge for) the list twice. You get the list back with status: "queued".
2. Poll GET /api/v1/lists/:id every 15–30 seconds until status is finished (or failed, with the reason in error). progress goes from 0 to 100.
3. Collect the rows as JSON from /results (filter by result, paginate) or as a CSV from /download.

Lists made over the API or MCP show up in the dashboard too, and createdVia tells you where each one came from. Results are deleted 30 days after the list was created, so collect them before expiresAt.

Errors

Errors use standard HTTP status codes and one JSON shape: { "error": code, "message": text, "field"?: name }, sometimes with extra fields (for example balance). Branch on error. message is written for people and may change.

{
  "error": "forbidden",
  "message": "Missing scope: lists:write"
}

Rate limits

Each key gets 120 requests per minute by default, counted in fixed one-minute windows. MCP tool calls count against the same budget, one request per call, except verify_emails, which counts one per distinct address. Over the limit, the API answers 429 rate_limited and MCP tools return a rate_limited error. Wait Retry-After seconds, then carry on.

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1791798360
Cache-Control: no-store

Idempotency

POST /api/v1/lists spends credits, so retries need care. Send an Idempotency-Key header: 1–255 characters, one per list you mean to create (a UUID works).

• Same key and same body after the first request finished: you get the original response again, with Idempotent-Replayed: true. No second list, no second charge.
• Same key while the first request is still running: 409 idempotency_in_progress.
• Same key with a different body: 422 idempotency_key_reused.
• If the first request failed with an error, the key is released and you can retry with it.
• Keys are remembered for 24 hours.
• Over MCP, create_list takes the same thing as its idempotency_key argument.

Single checks don’t need a key: re-checking an address within 30 days is free.

MCP server

ZenVerifier runs a remote Model Context Protocol server, so Claude, Cursor and other MCP clients can check addresses and run lists for you, using the same API keys, credits and rate limits.

Endpoint

https://www.zenverifier.com/api/mcp

Transport

Streamable HTTP, stateless, JSON responses. POST only.

Auth

Authorization: Bearer zv_live_… with the mcp:access scope. Use an “AI agent (MCP)” preset.

The quickest route: in the dashboard, API & MCP → Generate key & copy config creates a key and copies your client’s config with the key filled in. To set it up by hand, replace zv_live_YOUR_KEY below with your key.

claude mcp add --transport http zenverifier https://www.zenverifier.com/api/mcp --header "Authorization: Bearer zv_live_YOUR_KEY"

Tools

mcp:access lets a key connect; its other scopes decide which tools it sees. A read-only agent key can look up lists and history but can’t spend credits. Tool errors come back as tool results with isError: true and the same codes as the REST API.

• The first time a key makes an MCP call, owners and admins get an email. Every call is logged (tool, client, status, duration) and the latest ones show under API & MCP in the dashboard. Call logs are kept for 90 days.
• Give each client its own key, so you can revoke one without breaking the others. Only paste keys into clients you trust.

Data retention

• Bulk lists and their results are deleted 30 days after the list was created. Every list carries expiresAt; after that it returns 404 not_found.
• API keys are stored only as hashes. The full key is never logged and never emailed.
• See Privacy, DPA and Security for the rest.