Introduction

ShieldSignup is a signup-time risk API. You send an email address to POST /v1/assess — and, for full coverage, the end user's public IP. You get back a verdict (allow, challenge, block), a numeric score (0–100), machine-readable reason codes, and the underlying signals used to score the request. Your code decides what to do with the verdict.

Email is required. IP is optional but strongly recommended in production. Without a usable IP, assessments use email and domain signals only. Values like 127.0.0.1 and private LAN addresses are accepted but ignored server-side — see Getting the client IP.

When to use it

• At account creation — call ShieldSignup before you write the user to your database.
• At email-gated features — trial activations, referral codes, free credits.
• At password reset — to catch account takeover attempts.

What you get back

This is a full-assessment response from a live (sk_live_…) request with a usable public IP. Use it to plan your data model and error handling. When no usable IP is available, signals.ip is omitted and ip_provided is false.

{
  "request_id": "req_01hw5k3mfvx8t2b4ncqw7ydpej",
  "session_id": "sess_abc123",
  "verdict": "block",
  "score": 91,
  "reasons": [
    {
      "code": "email_disposable",
      "signal": "email"
    },
    {
      "code": "ip_anonymizer",
      "signal": "ip"
    },
    {
      "code": "ip_reputation",
      "signal": "ip"
    }
  ],
  "signals": {
    "email": {
      "disposable": true,
      "domain": "mailinator.com",
      "domain_age_days": 9201,
      "mx_valid": true,
      "public_domain": false,
      "role_account": false
    },
    "ip": {
      "address": "185.220.101.45",
      "tor": true,
      "vpn": false,
      "proxy": false,
      "datacenter": false,
      "abuse_score": 97,
      "country_code": "DE",
      "asn": "AS200651"
    },
    "velocity": {
      "ip_signups_1h": 8,
      "ip_signups_24h": 22,
      "email_domain_1h": 14,
      "email_domain_24h": 31
    }
  },
  "ip_provided": true,
  "ip_status": "ok",
  "processed_ms": 18,
  "assessed_at": "2026-05-10T10:14:33Z"
}

The full field-level reference (types, required vs optional, every reason code) lives in API reference: assess.

How the verdict works

The verdict is derived from score using the thresholds configured for your account. Defaults:

Thresholds are configurable per account or per API key in Dashboard → Settings → Thresholds. Always treat all three values as possible — never assume the API only returns allow.

What ShieldSignup does not do

Next, follow the Quickstart to get a working integration in under ten minutes.