Quickstart

validkit is one API for phone, email, and IP validation. Every endpoint takes a small JSON body, returns one consistent envelope, and costs exactly 1 credit per record. Sign up to get an API key and 500 free credits a month.

Authentication

Pass your key in the Authorization header as a bearer token (or in X-Api-Key). Keys are managed in the dashboard.

Your first request

curl

curl -X POST https://validkit.shovelware.ai/api/v1/validate/email \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@acme.com"}'

JavaScript (Node 18+ / browsers / workers)

const res = await fetch("https://validkit.shovelware.ai/api/v1/validate/email", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VALIDKIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "jane@acme.com" }),
});
const { result, credits } = await res.json();
console.log(result.deliverability, credits.remaining);

Python

import os, requests

res = requests.post(
    "https://validkit.shovelware.ai/api/v1/validate/email",
    headers={"Authorization": f"Bearer {os.environ['VALIDKIT_API_KEY']}"},
    json={"email": "jane@acme.com"},
)
data = res.json()
print(data["result"]["deliverability"], data["credits"]["remaining"])

Response envelope

Successful responses always look like this:

{
  "success": true,
  "result": { ... },                  // see per-type docs
  "credits": { "used": 1, "remaining": 499 },
  "response_time_ms": 42
}

Errors are equally predictable:

{
  "success": false,
  "error": {
    "code": "insufficient_credits",  // machine-readable
    "message": "..."                 // human-readable
  }
}

Error codes: missing_api_key, invalid_api_key, insufficient_credits (HTTP 402), rate_limited (429), invalid_json, missing_field, too_many_items. Failed requests (4xx/5xx) never consume credits.

Bulk validation

Send up to 100 records per call — types can be mixed. Each record costs 1 credit; the whole batch is rejected up front with 402if your balance can't cover it.

curl

curl -X POST https://validkit.shovelware.ai/api/v1/validate/bulk \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"type": "email", "value": "jane@acme.com"},
      {"type": "phone", "value": "+14155552671"},
      {"type": "ip",    "value": "8.8.8.8"}
    ]
  }'

Prefer a no-code path? The dashboard has a CSV upload tool that validates up to 10,000 rows and returns an enriched CSV.

Rate limits

Free: 1 request/second. Paid plans: 10 requests/second. Exceeding the limit returns 429 rate_limited — back off and retry.

Try it live

Live request against the real engine — no signup needed. Rate-limited; sign up for 500 free credits.