Quickstart: Score your first signup

Before you start

You need a Signup Risk API account and an API key. The Free plan works for this tutorial: 200 requests and 50 explanations per month, no credit card required.

Account Create one at app.signuprisk.com/sign-up.

API key In the dashboard, open API Keys and select Create key. Copy the secret right away; it is shown once. Production keys start with eisk_live_, test keys with eisk_test_.

Server-side environment Keep the key in a server-side environment variable or secret manager. Never put it in browser code, mobile bundles, or source control. Call the API from your backend.

JSON client You can test with curl, Postman, Insomnia, or your application code.

Read the response

The response has up to five top-level objects: email and decision always, checks and explanation when you ask for them, and metadata always (usage, warnings, plan context, and cache status when a result came from the cache). Illustrative response, not a real API result. Trimmed to email, decision, and metadata; the values are the illustrative example from the docs quickstart. Your scores depend on current data, and metadata reflects your own account.

{
  "email": {
    "input": "maria.garcia@protonmail.com",
    "normalized": "maria.garcia@protonmail.com",
    "normalized_preserving_case": "maria.garcia@protonmail.com",
    "canonical": "maria.garcia@protonmail.com",
    "is_well_formed": true,
    "format_issues": [],
    "format_explanation": "The email address is structurally well formed. This does not mean it is safe, trusted, deliverable, or non-disposable.",
    "is_internationalized": false
  },
  "decision": {
    "action": "allow",
    "risk_score": 5,
    "risk_band": "low",
    "summary": "Low-risk signup. No significant risk checks failed.",
    "assessment": {
      "confidence": "high",
      "evidence_strength": "moderate",
      "evidence_coverage": "broad",
      "uncertainty": "low",
      "limitations": []
    }
  },
  "metadata": {
    "warnings": [],
    "usage": {
      "requests": { "used": 1, "limit": 10000, "unlimited": false, "remaining": 9999 },
      "explanations": { "used": 0, "limit": 500, "unlimited": false, "remaining": 500 }
    },
    "plan": {
      "current_plan": "Developer",
      "billing_period": { "starts": "2026-09-16T00:00:00Z", "ends": "2026-10-16T00:00:00Z" },
      "reset_at": "2026-10-16T00:00:00Z"
    },
    "assessment_version": "2026.08.28"
  }
}

The example account is on the Developer plan: 10,000 requests and 500 explanations per month, 30 requests per minute.

What to read first

• decision.action: the recommendation (allow, review, or block).
• decision.risk_score and decision.risk_band: how risky the signup looks (Step 3).
• decision.assessment: how strongly the available evidence supports the decision. confidence is high, medium, or low; limitations lists caveats such as name_not_supplied or ip_not_supplied.
• email.canonical: an identity form that folds googlemail.com into gmail.com and strips plus-addressing (and Gmail dots). Use it to spot repeat signups. It is not a delivery address.
• metadata.warnings: non-fatal notices. A warning never means the request failed.

Checks. With include_checks, all eight checks are returned: disposable_email, domain_infrastructure, provider, role_address, domain_typo, synthetic_identity, name_match, and ip_reputation. Most checks have a result, confidence, method, evidence, and risk_contribution, plus fields of their own. Here is the docs' illustrative checks.disposable_email for a clean address (illustrative, not a real API result):

{
  "result": "none",
  "confidence": "high",
  "method": "dataset_exact",
  "evidence": [],
  "risk_contribution": 0,
  "is_disposable": false
}

When a check could not be evaluated, its result is unknown and it contributes 0. A temporary DNS failure shows up as unavailable on domain_infrastructure. Unavailable evidence is never counted as a pass or a failure. Explanation. With include_explanation, the explanation object adds a plain-language summary, top_reasons (each an object with reason, check, and contribution), risk_factors and neutral_factors (each with factor and contribution), and a recommendation_reason. Explanations use a separate monthly allowance. If it runs out, the analysis still succeeds and explanation.explanation_available is false. Exact fields can vary by plan and options. The API reference is the source of truth for the full response schema.

Use the recommendation in your app

The fastest way to integrate the API is to use decision.action directly in your signup flow.

function routeSignup(result) {
  switch (result?.decision?.action) {
    case "allow":
      return {
        action: "create_account",
        message: "Signup allowed."
      };
    case "review":
      return {
        action: "hold_for_review",
        message: "Signup needs additional verification."
      };
    case "block":
      return {
        action: "deny_signup",
        message: "Signup blocked due to risk findings."
      };
    default:
      return {
        action: "hold_for_review",
        message: "Unknown recommendation. Review manually."
      };
  }
}

For early integrations, start by allowing low-risk signups, reviewing uncertain signups, and blocking only the highest-risk attempts. You can tighten rules later as you learn your product's normal signup patterns.

Scoring more than one address

• Batch: POST /v1/analyze-email/batch scores up to 50 emails per request, on every plan. Each email uses one request from your monthly allowance and counts as one unit against your per-minute rate limit. A full 50-email batch needs at least 50 requests per minute (Growth and above), so on Free (5 per minute) or Developer (30 per minute), keep each batch within your plan's per-minute limit. See Analyze up to 50 emails.
• Bulk CSV: asynchronous bulk jobs (/v1/bulk/jobs) are available on Scale and above, for files up to 1,000,000 rows. See Create a bulk job.