Check your first signup in ten minutes.

SignupVet checks the email, phone number and IP address of a new signup and returns one risk score with the reasons behind it.

1. Create a free account. 250 checks a month are free, no credit card.
2. In the dashboard, create an API key. It is shown once, so store it as a secret (e.g. SIGNUP_API_KEY).
3. From your server, send the signup to POST /score.
4. Act on recommendation: allow, review or block.

curl -X POST https://www.signupvet.com/score \
  -H "Authorization: Bearer $SIGNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "bot123@mailinator.com", "ip": "178.197.224.1"}'

Authentication

Every API request needs a key. Send it as a bearer token, or in the X-API-Key header.

Authorization: Bearer sv_live_…

Keys belong to your account and can be revoked in the dashboard at any time. Call the API from your server only; a key in browser code can be copied by anyone.

Code examples

All examples call /score with a 2-second timeout and fail open: if the API cannot be reached, the signup goes through. Your signup form never breaks because of us.

curl -X POST https://www.signupvet.com/score \
  -H "Authorization: Bearer $SIGNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@gmail.com",
    "phone": "+41 79 123 45 67",
    "ip": "178.197.224.1",
    "context": { "timezone": "Europe/Zurich" }
  }'

// signup-check.js (Node 18+, no dependencies)
export async function checkSignup({ email, phone, ip, timezone }) {
  try {
    const res = await fetch("https://www.signupvet.com/score", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.SIGNUP_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email, phone, ip, context: timezone ? { timezone } : undefined }),
      signal: AbortSignal.timeout(2000),
    });
    if (!res.ok) return { recommendation: "allow", reason_codes: [] }; // fail open
    return await res.json();
  } catch {
    return { recommendation: "allow", reason_codes: [] }; // timeout or network error: fail open
  }
}

// app/api/signup/route.ts (Next.js App Router)
import { checkSignup } from "@/lib/signup-check";

export async function POST(req: Request) {
  const { email, password, timezone } = await req.json();
  const ip = req.headers.get("x-forwarded-for")?.split(",")[0]?.trim();

  const check = await checkSignup({ email, ip, timezone });
  if (check.recommendation === "block") {
    return Response.json({ error: "Please sign up with a different email address." }, { status: 400 });
  }

  const user = await createUser({ email, password }); // your existing signup
  if (check.recommendation === "review") {
    await flagForReview(user.id, check.reason_codes); // e.g. no free credits until verified
  }
  return Response.json({ ok: true });
}

# signup_check.py (pip install requests)
import os
import requests

def check_signup(email=None, phone=None, ip=None, timezone=None):
    body = {k: v for k, v in {"email": email, "phone": phone, "ip": ip}.items() if v}
    if timezone:
        body["context"] = {"timezone": timezone}
    try:
        res = requests.post(
            "https://www.signupvet.com/score",
            headers={"Authorization": f"Bearer {os.environ['SIGNUP_API_KEY']}"},
            json=body,
            timeout=2,
        )
        res.raise_for_status()
        return res.json()
    except requests.RequestException:
        return {"recommendation": "allow", "reason_codes": []}  # fail open

Sending the browser time zone

Optional, but it enables the geo_mismatch check. Add a hidden field to your signup form:

<input type="hidden" name="timezone" id="timezone" />
<script>
  document.getElementById("timezone").value = Intl.DateTimeFormat().resolvedOptions().timeZone;
</script>

POST /score

The main endpoint for signups. Runs every check you send data for and combines them into one score. Also detects bot waves by comparing the signup with your recent signups.

At least one of email, phone or ip is required. Channels you do not send are null in signals.

How the score is combined

1. The strongest single finding counts in full (e.g. a disposable email: 85).
2. Every further channel that is suspicious on its own (score ≥ 30) adds 10 (multiple_risk_signals).
3. A phone number and IP from different countries add 15 (phone_ip_country_mismatch).
4. The result is capped at 100.

Bot-wave detection

Each /score call is compared with your earlier signups (never with other customers'). Matches are counted in signals.pattern and raise the score, see pattern codes. The comparison uses one-way fingerprints, not the original data.

{
  "request_id": "req_4f0c…",
  "status": "risky",
  "risk_score": 85,
  "risk_level": "critical",
  "recommendation": "block",
  "reason_codes": ["email_syntax_valid", "mx_records_present", "disposable_domain"],
  "signals": {
    "email": { "domain": "mailinator.com", "disposable_domain": true, "…": "…" },
    "phone": null,
    "ip": { "country": "CH", "city": "Basel", "is_datacenter": false, "…": "…" },
    "pattern": { "same_ip_10m": 0, "same_network_10m": 0, "email_series_1h": 0,
                 "same_domain_10m": 0, "phone_other_accounts_24h": 0 }
  },
  "confidence": 78,
  "provider": "signupvet",
  "latency_ms": 9,
  "policy": { "allow_threshold": 30, "review_threshold": 60, "block_threshold": 80 }
}

POST /verify/email

Checks only an email address. Request: email (required), ip, context (optional).

POST /verify/phone

Checks only a phone number. Request: phone (required), country_hint, ip, context (optional).

POST /verify/ip

Checks only an IP address. Request: ip (required), context (optional, timezone enables geo_mismatch).

Response format

Every endpoint returns the same envelope.

Reason codes

A score of +n is added on top of the strongest finding; plain numbers are the finding's own score. Codes with score 0 confirm that a check passed.

Email

Phone

IP address

Combined (/score)

Bot waves (/score)

Errors

Errors come as {"error": {"code": "…", "message": "…"}}. Only successful checks count towards your quota.

Limits and billing

• Every successful API call is one check, also when /score covers email, phone and IP together.
• Monthly checks of your plan are used first, then prepaid pack checks (which never expire).
• Rate limit: 10 requests per second per key, short bursts up to 20.
• Plans and usage are in the dashboard; prices on the pricing page.

Best practices

• Call from your server, never from the browser, so your key stays secret.
• Send the user's IP, not your server's. Behind a proxy or on Vercel, take the first address of X-Forwarded-For. A private IP (ip_private_or_reserved) usually means this went wrong.
• Fail open with a short timeout (1–2 s). A lost signup costs more than one missed bot.
• Start gentle. Block only block at first and log review. Tighten once you have seen your own data.
• Use review for friction, not rejection: require email confirmation, hold free credits, or ask for a phone number.
• Do not show reason codes to users. A neutral message ("Please use a different email address") tells bots less.

Supabase, Clerk and other auth providers

Call /score in the server-side code that creates the account, before you call your auth provider, for example in the API route or server action behind your signup form, right before supabase.auth.signUp() or creating the user in Clerk.

If users currently sign up directly from the browser with the provider's client SDK, move the signup behind your own endpoint first. Otherwise a bot can skip the check by talking to the provider directly.

Privacy

• Full email addresses, phone numbers and IPs are never stored. Your dashboard shows masked values such as m***@gmail.com and 178.197.224.x.
• Bot-wave detection uses one-way, keyed fingerprints and only compares signups within your own account.
• Checks run on our own data. Only when a paid carrier lookup is enabled is a phone number sent to that provider, and only for unclear cases.

IP Geolocation by DB-IP. Machine-readable API description: /openapi.json.