MultiValidator API Documentation
One endpoint, POST /api/v1/verify, discriminated by kind. It returns the checks that kind implies, each with the reason it produced — email, phone, WhatsApp and BIN through the same envelope. Bearer-token auth, JSON in and out.
Quick start
The verdict
Four states, a 0–100 score, and a didYouMean typo suggestion when one applies. BIN returns three of them — never unknown.
$ curl -X POST https://api.multivalidator.io/api/v1/verify \ -H "Authorization: Bearer mv_<64 hex>" \ -H "Content-Type: application/json" \ -d '{"kind": "email", "email": "sarah@bounced-host.example"}'{ "success": true, "data": { "email": "sarah@bounced-host.example", "status": "undeliverable", "classification": "invalid", "score": 0, "is_valid": false }, "credits": { "used": 1, "remaining": 418, "quality": "standard" }, "kind": "email", "target": "sarah@bounced-host.example", "state": "undeliverable", "qualityScore": 0, "latencyMs": 214, "stages": { "syntax": { "pass": true, "normalizedEmail": "sarah@bounced-host.example" }, "dns": { "pass": false, "reason": "Domain has no MX or A records" } }, "didYouMean": null, "creditsRemaining": 417.75, "creditsConsumed": 0.25}
The handshake, drawn
stage 04 · smtp — nothing is ever sentThe mailbox probe is a polite exchange that stops at RCPT TO. When the server refuses — as here, with a 550 — you get the raw code, and the verdict stops being a guess.
Authentication
Every authenticated call sends a bearer token. Keys are created in Dashboard → API keys and revoked the same way. Keep them server-side: a key is a billing address.
- Only a SHA-256 hash of the key and its 8-character prefix are stored. The full key is returned once and can never be recovered.
- Revoking a key is a soft revoke: the row stays, the key is set inactive, and requests using it fail immediately with 401.
- An exposed key is a spent key. Never ship one in frontend JavaScript, a public repository or a client-side environment variable — revoke it and create a replacement the moment it leaks.
- The rate limit is per account tier, not per key — three keys do not buy three budgets.
Authorization: Bearer mv_<64 hex># Every authenticated endpoint takes the same header.# Public integrations should use /api/v1/public/* so your own# clients and your app can evolve independently.
API keys
Three calls, all session-authenticated: create, list, revoke. A key cannot mint another key.
POST /api/v1/keystakes{ "name": "…" }. The response carries the full key once — store it then, because it is never shown again.GET /api/v1/keyslists names, prefixes, request counts and last-used times. Never the secret.DELETE /api/v1/keys?id=…revokes one key softly: it stops working, and the audit trail survives.
# Dashboard session only — API-key management is not an API-key endpoint.# Create — the secret comes back once$ curl -X POST https://www.multivalidator.io/api/v1/keys \ -H "Cookie: <your dashboard session cookies>" \ -H "Content-Type: application/json" \ -d '{"name": "Production"}'{ "id": "…", "key": "mv_<64 hex>", "prefix": "mv_1234abcd", "createdAt": "…" }# List$ curl https://www.multivalidator.io/api/v1/keys \ -H "Cookie: <your dashboard session cookies>"# Revoke — soft: the key is set inactive, the row stays$ curl -X DELETE "https://www.multivalidator.io/api/v1/keys?id=<id>" \ -H "Cookie: <your dashboard session cookies>"
The request
One endpoint. kind decides everything else: which field holds the target, which checks run, and which checks come back.
{"kind": "email", "email": "you@example.com"}
phone
{"kind": "phone", "phone": "+14155550134"}
{"kind": "whatsapp", "whatsapp": "+14155550134"}
bin
{"kind": "bin", "bin": "424671"}
target is an accepted alias for the kind’s own field, and kind may be omitted when the field itself makes it unambiguous. quality applies to email only — phone, WhatsApp and BIN ignore it.
| Field | Type | Required | Notes |
|---|---|---|---|
| kind | string | No | email, phone, whatsapp or bin. Defaults to email. Any other value is a 400. |
| string | For kind=email | The address to verify. A value that fails its own format rule returns 400 with INVALID_EMAIL. | |
| phone | string | For kind=phone | The number to resolve — international format gives the most reliable result. |
| string | For kind=whatsapp | An E.164 number (for example +14155552671). Checks whether the number is registered on WhatsApp. | |
| bin | string | For kind=bin | Six to eight digits; a longer value is truncated to its first eight. |
| target | string | No | Accepted alias for whichever field the kind uses. |
| quality | string | No | standard, high or extreme. Email only; each tier has its own current per-row price. Deeper tiers retry slow, greylisting or temporarily unavailable servers; they never return extra fields. |
Bodies are size-limited: an oversized request is refused with 413 rather than being parsed.
An unknown verdict caused by a timeout or a temporarily unavailable server can be re-requested at a higher quality. The dashboard offers this as a one-click retry; API clients simply call again with quality set to high or extreme. Definitive verdicts never change with quality — the deeper tiers buy patience, not new fields.
Response schema
Every field, drawn in place — hover either side to trace a field from the payload to its meaning. The envelope holds for all four kinds; the detail block inside it does not.
POST /api/v1/verify · 200
{"email": "sarah@bounced-host.example","state": "undeliverable","qualityScore": 0,"stages": {"syntax": { "pass": true },"dns": { "pass": false, "reason": "Domain has no MX or A records" }},"reason": "mx_not_found","didYouMean": null,"latencyMs": 214}
Field map · hover to trace
- emailstring
The address as sent, unchanged.
- stateenum
deliverable · risky · undeliverable · unknown
- qualityScorenumber 0–100
Computed from the stage outcomes; a probability, not a promise.
- stagesobject
One entry per stage with pass and reason. The audit trail.
- reasonstring · optional
Present when a stage fails hard — e.g. mx_not_found.
- didYouMeanstring · nullable
Typo suggestion for the domain when one applies.
- latencyMsnumber
Time spent in the pipeline, in milliseconds.
| Kind | Detail block | Shape |
|---|---|---|
| stages | One entry per stage — syntax, dns, disposable, smtp, spam-trap, role, free-email — each with pass and reason. | |
| phone | checks + details | One entry per check with outcome pass/warn/skip and a reason, plus the resolved detail fields. |
| checks + details | Format, registration and JID checks, plus details.exists and details.jid. Deliverable means the number is registered on WhatsApp. | |
| bin | checks + details | The same shape as phone. A range that is not found returns a single, failed dataset check. |
That asymmetry is deliberate and worth reading twice: email returns stages, while phone, WhatsApp and BIN return checks — same envelope, different detail block.
Score rules
Email scores are a weighted composition: the stage outcomes allocate a hundred points, and the score is what they add up to. The marker shows where a verdict lands.
Phone, WhatsApp and BIN are not weighted at all. Each state maps to one fixed score — deliverable 92, risky 62, undeliverable 12, unknown 35 — because there is no set of sub-scores to add up.
Bulk email is the one path where an email score is clamped: the same stage outcomes use the same weights, and the result is then held inside the band its verdict allows — a risky row cannot score above 70, and a deliverable row is lifted to at least 80. Single requests score the raw sum.
Verdicts
The state is the answer; the score is context. Four states exist across the API, and one kind uses three of them.
- deliverablethe value is live and ordinary — a mailbox that accepts, a range that is listed
- riskyreachable but flagged: VoIP, disposable, catch-all, greylisted, prepaid, or elevated provider risk
- undeliverablea check failed hard — no mail route, a rejected number, or a range the dataset does not hold
- unknownno definitive answer came back, and we say so rather than guess
BIN never returns unknown: the dataset either holds the range or it does not, so a miss is reported as undeliverable and described as unlisted, not disproven.
Phone lookup
Phone checks run inline — no queue, no polling, the same request returns the result — at the current per-lookup rate whatever quality says, because the field applies to email only.
{ "kind": "phone", "phone": "+14155550134"}
{ "success": true, "data": { "kind": "phone", "target": "+14155550134", "status": "deliverable", "classification": "safe", "score": 92, "is_valid": true }, "credits": { "used": 1, "remaining": 418, "quality": "standard" }, "qualityScore": 92, "latencyMs": 412, "checks": [ { "key": "format", "label": "Format", "outcome": "pass" }, { "key": "line_type", "label": "Line type", "outcome": "pass", "reason": "Line type is mobile." }, { "key": "carrier", "label": "Carrier", "outcome": "pass", "reason": "Carrier identified as Twilio." }, { "key": "risk", "label": "Risk", "outcome": "pass", "reason": "Provider risk score: 8." } ], "details": { "provider": "multivalidator", "classification": "safe", "phone": "+14155550134", "rawInput": "415 555 0134", "lineType": "mobile", "carrier": "Twilio", "countryCode": "US", "countryName": "United States", "nationalNumber": "4155550134", "valid": true, "isDisposable": false, "riskScore": 8, "timezones": ["America/Los_Angeles"] }}
| Detail field | Meaning |
|---|---|
| lineType | mobile, landline, voip or unknown. VoIP is flagged risky, never invalid. |
| carrier | The carrier the range resolves to, when the lookup returns one. |
| countryCode / countryName | The country the number parses into. |
| nationalNumber | The number without its calling code. |
| valid | Whether the range is a reachable number at all. |
| isDisposable | Throwaway or virtual number services. |
| riskScore | Upstream risk score, 0–100. Medium and high map to risky. |
| timezones | Timezones associated with the range — useful for send-time decisions. |
All four verdicts apply: deliverable, risky for VoIP, disposable or an elevated risk score, undeliverable for a number that does not parse, and unknown when the lookup returns no verdict on the range.
BIN check
A BIN check resolves the first six to eight digits of a card to its issuing bank and characteristics — inline, at the current per-lookup rate. Six digits is the sweet spot; longer input is truncated to eight.
{ "kind": "bin", "bin": "424671"}
{ "success": true, "data": { "kind": "bin", "target": "424671", "status": "deliverable", "classification": "safe", "score": 92, "is_valid": true }, "credits": { "used": 1, "remaining": 418, "quality": "standard" }, "qualityScore": 92, "latencyMs": 551, "checks": [ { "key": "dataset", "label": "Dataset match", "outcome": "pass", "reason": "BIN 424671 found in provider dataset." }, { "key": "issuer", "label": "Issuer", "outcome": "pass", "reason": "Issuer: Northbridge Bank." }, { "key": "risk", "label": "Risk profile", "outcome": "pass", "reason": "BIN has no elevated risk flags in provider metadata." } ], "details": { "provider": "multivalidator", "classification": "safe", "bin": "424671", "found": true, "notFoundReason": null, "scheme": "visa", "funding": "credit", "brand": "Visa", "category": "classic", "countryCode": "US", "countryName": "United States", "issuerName": "Northbridge Bank", "currency": "USD", "prepaid": false, "commercial": false, "longerBinAvailable": true }}
| Detail field | Meaning |
|---|---|
| found | Whether the dataset holds the range. A miss also fills notFoundReason. |
| scheme / funding / brand / category | The card network, credit or debit, brand tier and category. |
| countryCode / countryName | The issuing country. |
| issuerName | The issuing bank, when the dataset carries it. |
| currency | The currency the range bills in. |
| prepaid / commercial | Either flag makes the range risky: prepaid cards and corporate ranges behave differently. |
| longerBinAvailable | A longer prefix exists and would classify more precisely — the lookup says so instead of guessing. |
BIN returns exactly three verdicts: deliverable, risky for prepaid, commercial or unknown-network ranges, and undeliverable when the dataset does not hold the range. It never returns unknown.
Bulk overview
Bulk takes the same kinds through the same engine. Email queues; phone, WhatsApp and BIN come back completed. Charged per row at the current rate, spent only when a row is checked. Non-email lists can be sent as targets, values, or the kind’s own array — phones, whatsapps or bins.
Queued. Submit with POST /api/v1/bulk, poll GET /api/v1/bulk/{jobId}, then read the returned results.
phone
Inline. The submission returns completed results — nothing to poll.
Inline. Send targets or whatsapps; one registered/not-registered verdict per row.
bin
Inline. Same submission, completed results, three verdicts.
The dashboard pages for each job describe the same behaviour: bulk email, bulk phone, bulk BIN.
CSV upload
A multipart upload: the file plus the kind you want the columns detected for. Headers are read from row one.
- CSV or TSV, one file at a time. Column detection combines a header hint with a value-shape test.
- A cell holding several values is split on commas, semicolons, pipes, tabs and newlines, then de-duplicated.
- The response returns the detected column per kind, how many rows matched, and a preview of the first rows.
# Dashboard session only. API-key clients send emails as JSON to POST /api/v1/bulk.$ curl -X POST https://www.multivalidator.io/api/v1/bulk/upload \ -H "Cookie: <your dashboard session cookies>" \ -F "file=@leads.csv" \ -F "kind=email"{ "filename": "leads.csv", "totalRows": 1284, "headers": ["email", "name", "notes"], "detectedColumns": { "email": ["email"], "phone": [], "whatsapp": [], "bin": [] }, "suggestedColumns": { "email": "email" }, "matchedRowsByKind": { "email": 1102 }}
Job lifecycle
Only email has a lifecycle to manage. Submit, poll, download — and phone, WhatsApp or BIN skip straight past it.
POST /api/v1/bulkwith{ kind: "email", emails: [...] }returns a job id rather than results.GET /api/v1/bulk/{jobId}reports processed rows, per-state counts and skipped rows while it advances.- When the status reads completed, the results are ready to download. A failed job says so with an error message.
# API-key clients: submit, then poll the canonical job endpoint.$ curl -X POST https://www.multivalidator.io/api/v1/bulk \ -H "Authorization: Bearer mv_<64 hex>" \ -H "Content-Type: application/json" \ -d '{"kind": "email", "emails": ["sarah@a.example", "jordan@b.example"]}'$ curl "https://www.multivalidator.io/api/v1/bulk/<jobId>" \ -H "Authorization: Bearer mv_<64 hex>"# phone, WhatsApp and BIN never queue — the same POST returns completed results$ curl -X POST https://www.multivalidator.io/api/v1/bulk \ -H "Authorization: Bearer mv_<64 hex>" \ -H "Content-Type: application/json" \ -d '{"kind": "whatsapp", "whatsapps": ["+14155552671", "+14155552672"]}'
Downloads
API-key clients receive results in the job response. A dashboard session can download the results CSV — the same rows uploaded, with verdicts appended and skipped rows marked at zero charge.
Both paths are scoped to the job id and your account. A job that has not completed has nothing to return yet. CSV download is dashboard-session only; API keys use GET /api/v1/bulk/{jobId}.
# API-key job poll: results arrive in the body once status is completed.$ curl "https://www.multivalidator.io/api/v1/bulk/<jobId>" \ -H "Authorization: Bearer mv_<64 hex>"{ "job_id": "<jobId>", "status": "completed", "progress": { "total": 2, "completed": 2, "failed": 0, "skipped": 0 }, "credits": { "used": 0.5, "remaining": 417.5 }, "results": [ { "email": "sarah@a.example", "status": "deliverable" } ]}
Webhooks
Register an HTTPS endpoint and we POST to it when a job finishes. Two events exist.
verification.completedfires for API-key requests only — a dashboard check does not deliver it. Its data also carriesconfidence(highormedium): how strongly independent local checks corroborate the verdict.bulk.completedfires when a bulk job finishes, from the dashboard or the API. Its data carries the job id, filename and per-state counts.- When the endpoint has a secret, every request carries
X-MultiValidator-Signature: an HMAC-SHA256 of the exact JSON body, hex-encoded, prefixedsha256=. - Delivery is HTTPS-only, refuses redirects, times out after five seconds, and will not call a host that resolves to a private address.
{ "event": "verification.completed", "data": { "kind": "email", "target": "sarah@bounced-host.example", "email": "sarah@bounced-host.example", "state": "undeliverable", "latencyMs": 214, "stages": { "dns": { "pass": false, "reason": "Domain has no MX or A records" } }, "didYouMean": null, "quality": "standard", "confidence": "high" }, "timestamp": "2026-09-24T12:00:00.000Z"}
Retries
A delivery that is not answered with a 2xx is retried, up to five attempts in total.
schedule
One immediate attempt, then backoff at 1, 5, 15 and 60 minutes. After the last attempt the delivery is marked failed and stops — there is no indefinite retry.
who retries
A queue worker picks up whichever deliveries are due. Each row is claimed atomically, so a delivery is attempted by exactly one worker — the request path or the worker, never both.
Answer 2xx early and do the slow work afterwards. Because a delivery can be retried, treat each event as at-least-once and key your own handling on the event and its timestamp.
Endpoints
Every route below exists in the application. Anything not listed here is not part of the public surface.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/health | Service health check. No API key required. |
| POST | /api/v1/public/verify | Public developer endpoint. API key required. Same verification engine, credits, and webhooks as /api/v1/verify. |
| GET | /api/v1/public/usage?days=30 | Public API-key usage analytics (request and credit consumption snapshots). |
| POST | /api/v1/public/bulk | Submit a bulk verification job with JSON emails (API key). |
| GET | /api/v1/public/bulk/{jobId} | Poll a public bulk API job and receive results once complete (API key). |
| POST | /api/v1/verify | Verify a single target. Body supports { kind:"email", email:"..." }, { kind:"phone", phone:"..." }, { kind:"whatsapp", whatsapp:"..." } or { kind:"bin", bin:"..." }. |
| POST | /api/v1/bulk | Canonical bulk endpoint for API-key clients. Email jobs are queued; phone/WhatsApp/BIN payloads return completed results inline. |
| GET | /api/v1/bulk/{jobId} | Canonical bulk job status endpoint for API-key clients. |
| GET | /api/v1/usage?days=30 | Usage analytics for authenticated users (dashboard session or API key). |
| GET | /api/v1/account | Account profile and credits summary (dashboard session or API key). |
| POST | /api/v1/webhook | Singular webhook creation alias (dashboard session only). |
| POST | /api/v1/bulk/upload | Dashboard session only: upload a CSV to storage for a bulk job. API keys use POST /api/v1/bulk with JSON emails. |
| POST | /api/v1/bulk/process | Dashboard session only: start processing an uploaded email job. Invalid or deselected rows are returned as skipped at zero charge. |
| GET | /api/v1/bulk/status?jobId=... | Dashboard session only: poll an uploaded bulk job’s progress. |
| GET | /api/v1/bulk/download?jobId=... | Dashboard session only: download the verified results CSV. API-key clients read results from GET /api/v1/bulk/{jobId}. |
| GET | /api/v1/keys | Canonical API-key contract: list keys (including revoked) for the signed-in account. |
| POST | /api/v1/keys | Create an API key (optional expires_at; secret is shown once). |
| DELETE | /api/v1/keys?id=... | Revoke one API key. |
| PATCH | /api/v1/keys | Suspend or re-enable (not revoke) an API key. |
| POST | /api/v1/webhooks | Create a webhook endpoint for verification.completed or bulk.completed (dashboard session only; signing secrets are shown once). |
| POST | /api/v1/billing/checkout | Create a Creem checkout session for a plan or credit pack. |
| POST | /api/v1/billing/portal | Open the Creem billing portal. |
| GET | /api/v1/tools/mx?domain=... | Free MX lookup for a domain: the mail exchanges, plus whether the domain has MX and A records. No API key — anonymous traffic is rate limited per IP. |
| GET | /api/v1/tools/dmarc?domain=... | Free DMARC record lookup: one TXT query at _dmarc.<domain>, returning the record, its parsed tags and any structural problems. No API key — anonymous traffic is rate limited per IP. |
Errors
The status tells you what happened; the code tells you what to do about it.
- 200Verification complete with the normalized contract.
- 400Invalid request shape or input — an unknown kind, a malformed target, or a bulk list over the size cap.
- 401Missing, invalid, revoked or expired API key.
- 402Insufficient credits for the requested volume or quality.
- 403The key is valid but not allowed to read that resource.
- 404The requested job id does not exist under your account.
- 413The request body is larger than the endpoint accepts.
- 429Rate limit exceeded. The reset timestamp is in the headers.
- 503The verification service behind a check could not be reached, or refused the request.
| Status | Code | Meaning |
|---|---|---|
| 401 | AUTH_REQUIRED | No bearer token was sent. |
| 401 | INVALID_API_KEY | The Authorization header is malformed, or the key is unknown. |
| 401 | API_KEY_EXPIRED | The key passed its expiry date. |
| 401 | API_KEY_REVOKED | The key was revoked and is no longer accepted. |
| 400 | INVALID_REQUEST | The body failed validation — an unknown kind, an oversized body, or a bulk list over the cap. |
| 400 | INVALID_EMAIL | The address failed its own format rule before any check ran. |
| 403 | FORBIDDEN | The request is authenticated but not permitted for this resource. |
| 404 | JOB_NOT_FOUND | No job exists with that id under your account. |
| 400 | BULK_TOO_LARGE | The submitted list is longer than the bulk cap for that endpoint. |
| 402 | INSUFFICIENT_CREDITS | Details carry requiredCredits and creditsRemaining. |
| 429 | RATE_LIMIT_EXCEEDED | Carries an X-RateLimit-Reset header. |
| 429 | DAILY_LIMIT_EXCEEDED | The plan's per-tool daily cap is reached. Details carry kind, limit, used, remaining and resetsAt; the response carries an X-DailyLimit-Reset header. |
| 502 / 503 | VERIFICATION_FAILED | The verification service could not complete the request. A single check is refunded; a bulk job whose provider is unreachable keeps its reservation for a safe retry. |
| 503 | PROVIDER_ERROR | The verification service returned an error the request could not recover from. |
| 500 | INTERNAL_ERROR | Something failed on our side. The message is generic on purpose. |
| 405 | INVALID_REQUEST | GET is disabled on /verify. The response carries Allow: POST. |
Errors arrive as { success: false, error: { code, message, details? } } — the same envelope as successes, so one parser handles both.
Rate limits
A sliding ten-second window, counted per account tier — shared across every key that account holds, and never counted per IP.
| Tier | Requests / 10s |
|---|---|
| Free | 30 |
| Starter | 100 |
| Growth | 300 |
| Enterprise | 1,000 |
- Successful responses carry
X-RateLimit-RemainingandX-RateLimit-Reset. - A 429 carries
X-RateLimit-Reset— read it and wait rather than retrying blind.
Credits
Each completed check is charged at the current rate. Mapping and preview cost nothing. A bulk row that is skipped — an invalid value or a row you deselected — is reported at zero charge, and a job paused for insufficient credits has not been submitted and costs nothing.
The current per-row rate depends on quality: standard, high or extreme.
Phone
The current per-lookup rate; the quality field applies to email only.
BIN
The current per-lookup rate. A row that cannot be read as a range is skipped.
Failed requests
A single check that did not complete is refunded. A bulk job that cannot be confirmed keeps its reservation for a safe retry.
Every response that costs anything says so: credits.used, credits.remaining and the mirrored creditsConsumed / creditsRemaining fields on the top level. All credit amounts are decimal credits with up to four decimal places (for example 0.25), never raw internal units.
Integration guides
Three shapes cover almost every integration. Each one names the endpoint it uses and the failure it has to handle.
Signup-form hook
POST /api/v1/verifyCall it inline as the address is submitted, with a short timeout and a fallback so a slow check never blocks the form. Handle 429 by letting the user through and checking later, and 402 by refusing the check rather than the signup.
CRM / back-office batch
POST /api/v1/bulkSubmit the list, keep the job id, poll GET /api/v1/bulk/{jobId} on an interval until it completes, then read the results in that response. Phone, WhatsApp and BIN payloads return their results on the same POST, so there is nothing to poll.
Webhook consumer
POST /api/v1/webhooksRegister an HTTPS endpoint, verify the signature header against your secret, answer 2xx quickly and do the slow work afterwards. A non-2xx is retried, so make your handler idempotent on the event and timestamp.
SDKs & libraries
There is no official SDK yet, in any language — so there is nothing to install and no package to keep up to date.
In the meantime the raw endpoints are the interface, and the samples above are complete: one POST, two headers, JSON in and out. A generated client would only wrap that.
MCP server
An MCP server is on the roadmap. It is not shipped, there is nothing to install, and this page will not pretend otherwise.
When it ships it will read the same endpoints documented here — the verification engine is the product, and MCP would be another way in, not a new capability.
Stop mailing ghosts.
Start with free credits. No card, no call, no “book a demo”.