Quickstart

Get your first Vouchley verification response in under five minutes. One API key, one POST request.

1. Create an API key

Sign in to the dashboard, open API Keys, and click Create new key. Keys are prefixed with vch_live_ for production and vch_test_ for sandbox. You will see the full key exactly once — copy it into your server-side environment immediately.

.env

export VOUCHLEY_API_KEY=vch_live_abc123...

2. Make your first request

Every verification is a single POST /v1/verify call. Pass the email you want to score — and optionally the signer name, company name, and source IP for richer signals.

Terminal

curl -X POST https://api.vouchley.getrevlio.com/v1/verify \
  -H "Authorization: Bearer $VOUCHLEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@acme.com",
    "name": "John Doe",
    "company_name": "Acme Inc.",
    "ip_address": "203.0.113.42"
  }'

3. Understand the response

Vouchley responds with a score (0–100), a plain-English recommendation — approve, review, or block — plus the raw signal breakdown your team can audit.

Response 200 OK

{
  "request_id": "req_8f3a0c921b",
  "score": 82,
  "recommendation": "approve",
  "email": {
    "valid": true,
    "disposable": false,
    "free_provider": false,
    "role_based": false,
    "mx_record": true
  },
  "company": {
    "domain": "acme.com",
    "domain_alive": true,
    "domain_age_days": 2847,
    "has_website": true
  },
  "person": {
    "name_matches_email": true,
    "confidence": 0.82
  },
  "ip": {
    "country": "IN",
    "is_vpn": false,
    "is_tor": false,
    "risk_score": 12
  },
  "flags": [],
  "reasoning": "Valid corporate email at a 7-year-old company domain. IP clean.",
  "cached": false,
  "processed_in_ms": 847
}

4. Wire it into your signup flow

Call Vouchley inside your signup handler, then branch on recommendation. A common pattern: auto-approve on approve, queue for manual review on review, reject outright on block.

signup.ts

async function createUser(signup) {
  const resp = await fetch("https://api.vouchley.getrevlio.com/v1/verify", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VOUCHLEY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: signup.email,
      name: signup.name,
      ip_address: signup.ip,
    }),
  });
  const { score, recommendation } = await resp.json();

  if (recommendation === "block") throw new Error("Signup rejected");
  if (recommendation === "review") await flagForManualReview(signup);

  return await db.users.insert({ ...signup, trust_score: score });
}

Next steps

You have a working integration. Continue with Authentication to learn how to rotate keys safely, read about Caching & Credits to understand how billing works, or jump to the API Reference for the full shape of every endpoint.