Quickstart

This page takes you from zero to a successful authenticated API request.

1. Get an API key

Create an account at app.signuprisk.com/sign-up.
In the dashboard, open API Keys and select Create key.
Copy the secret immediately. It is shown once and cannot be retrieved again.

Production keys use the format eisk_live_...; test keys use eisk_test_.... API keys are secrets. Keep them in server-side environment variables or a secret manager. Do not put API keys in browser code, client bundles, or source control — all requests should be sent from your backend. See Authentication for scopes, key rotation, and the full key lifecycle.

2. Authenticate

Every request carries your API key as a Bearer token in the Authorization header. This is the only accepted credential transport:

Authorization: Bearer eisk_live_example_public_id_example_secret

3. Make your first request

Send a POST request to the analysis endpoint with an email address:

Request

curl https://api.signuprisk.com/v1/analyze-email \
  -H "Authorization: Bearer eisk_live_example_public_id_example_secret" \
  -H "Content-Type: application/json" \
  -d '{"email":"maria.garcia@protonmail.com"}'

email is the only required field. Optional signup context is accepted on the same request:

Field	Type	Notes
`name`	string	Submitted name, used for name/email alignment
`ip`	string	Client IP for IP reputation (Growth plan and above)
`industry`	string	Industry profile key for industry-specific scoring (Scale plan and above)

Response-detail controls are nested under options:

{
  "email": "maria.garcia@protonmail.com",
  "options": {
    "include_checks": true,
    "include_explanation": true
  }
}

Use a real email address when testing. Documentation-reserved domains such as example.com, example.org, and example.net are special-use names that can never receive email, so the API deterministically returns block for them (risk score 100).

4. Interpret the response

The response below is illustrative — score values depend on current check data, and metadata.usage and metadata.plan reflect your own account:

Response

{
  "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 envelope has up to five top-level objects:

Key	Present	Contents
`email`	always	Normalized address, format validity, canonical identity form
`decision`	always	The action, score, band, summary, and decision-quality assessment
`checks`	when requested (`options.include_checks`)	Per-check verdicts, evidence, and score contributions
`explanation`	when requested (`options.include_explanation`)	Plain-language reasons behind the decision
`metadata`	always	Warnings, usage and quota snapshot, plan context

The decision to act on is decision.action — allow (0–24 risk score), review (25–74), or block (75–100). The action is a recommendation; enforcement is your application’s responsibility. For what every field means — normalization, the decision-quality assessment, per-check evidence, and metadata — see Understanding the Response. For how scoring works, see Core Concepts.

Troubleshooting

A 401 or 403 response means authentication or authorization failed — check the error.code in the response body (MISSING_API_KEY, INVALID_API_KEY, REVOKED_API_KEY, EXPIRED_API_KEY, INSUFFICIENT_SCOPE). See Authentication and the Error Reference for every code and its remedy.

Next steps

Authentication

API-key scopes, environments, safety, rotation, and lifecycle.

Understanding the response

What the decision, checks, explanation, and metadata mean.

API reference

Full request and response schemas for every customer-facing operation.

Getting Started

Concepts

API Reference

1. Get an API key

2. Authenticate

3. Make your first request

4. Interpret the response

Troubleshooting

Next steps

Authentication

Understanding the response

API reference