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.get('SIGNUP_API_KEY', '')}"},
            json=body,
            timeout=2,
        )
        res.raise_for_status()
        return res.json()
    except requests.RequestException:
        return {"recommendation": "allow", "reason_codes": []}  # fail open

More complete examples (Express, Next.js with Supabase, FastAPI) are on GitHub: github.com/signupvet/examples. Step-by-step guides: Express, FastAPI, Next.js, Supabase, Clerk, Firebase, Better Auth.

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)

Your own rules (/score)

Your own rules

On the Build, Growth and Scale plans you can adjust /score to your product in the dashboard. The rules apply to /score only, from the next request on.

Thresholds

Set from which score a signup is sent to review (default 30) and from which score it is blocked (default 80). The policy field of every /score response shows the thresholds that were used.

Block and allow lists

• Email domain, for example spammer.com. Also covers subdomains such as mail.spammer.com.
• Email address. Dots and +tags in the part before the @ are ignored, so jane.doe+x@company.com matches janedoe@company.com.
• Phone number in international format, for example +41791234567.
• IP address, a single IPv4 or IPv6 address.

A block list match returns block with score 100 and customer_blocklist. An allow list match returns allow with customer_allowlist; the score still shows what the checks found. If a signup is on both lists, the block list wins.

An allowed email domain lets in anyone who types an address at that domain, without proving they own it. Keep confirming email addresses as usual.

Email addresses, phone numbers and IPs in your lists are stored like the check logs: masked plus a one-way fingerprint, never in full. Email domains are stored as entered. Up to 1,000 entries per account. If you move back to the Free plan, your rules are kept but not applied.

Webhooks

On the Build, Growth and Scale plans you can add one HTTPS endpoint in the dashboard. After a /score call that ends in block we send it a POST request with a JSON event (signup.blocked). Tick the box to also get signup.review. The API response itself is not delayed: events are sent right after it.

{
  "id": "evt_4f1c…",
  "type": "signup.blocked",
  "created": "2026-10-29T14:03:11.402Z",
  "data": {
    "request_id": "req_4f1c…",
    "recommendation": "block",
    "risk_score": 85,
    "risk_level": "critical",
    "reason_codes": ["email_syntax_valid", "mx_records_present", "disposable_domain"],
    "email": "s***@mailinator.com",
    "phone": null,
    "ip": "178.197.224.x"
  }
}

• Email, phone and IP are sent masked, like in your dashboard. Use request_id to match the event to your own signup record.
• Answer with any 2xx status within 5 seconds. On a network error, a 5xx or 429 we try twice more (after 2 and 10 seconds). Events can arrive more than once; id is unique per event.
• Only public HTTPS addresses are accepted, and redirects are not followed.
• Slack: paste a Slack incoming webhook URL (https://hooks.slack.com/…) and you get a readable message in your channel instead of the JSON event.

Checking the signature

Every request has a SignupVet-Signature header: t=<unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of <t>.<raw request body> with your signing secret (whsec_…, shown in the dashboard). Compute it on the raw body before parsing the JSON.

// Node 18+: check the signature before you trust the event.
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySignupVetEvent(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const ok = parts.v1?.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300; // 5 minutes
  return ok && fresh;
}

The dashboard has a Send test event button (event type test) and shows the result of the last delivery.

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.
• Check logs are deleted automatically after 90 days.
• 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.