# Domain Risk API — fraud and brand-protection intelligence: 0-100 risk score, domain age and expiry lifecycle, parked/for-sale detection, typosquat and lookalike generation with registration checks, registrar, nameserver and email reputation (RDAP + DNS + Certificate Transparency, no API key required)

> Comprehensive fraud and security risk report for one domain: a 0-100 risk score, human-readable reasons, and a risk level (low / medium / elevated / high). Combines domain age, expiry status, parked/for-sale detection, TLS certificate presence, hostname structure, brand impersonation signals, and email/DNSSEC legitimacy into a single verdict. The primary action for phishing detection and brand protection.
> ReefAPI engine `domain-risk` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/domain-risk/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /domain-risk/v1/assess — 1 credit
Comprehensive fraud and security risk report for one domain: a 0-100 risk score, human-readable reasons, and a risk level (low / medium / elevated / high). Combines domain age, expiry status, parked/for-sale detection, TLS certificate presence, hostname structure, brand impersonation signals, and email/DNSSEC legitimacy into a single verdict. The primary action for phishing detection and brand protection.

**Parameters:**
- `domain` (string, required) — A full domain to evaluate (e.g. example.com, secure-login.io). A bare host, full URL, leading www., or an IDN (münchen.de) are accepted and normalized to its registrable form.
- `check_parked` (boolean, optional, default true) — If true (default), also fetch the domain's root page to detect a parked or for-sale landing page. A failed page probe never fails the overall risk assessment — only the parking signal is omitted.
- `include_pii` (boolean, optional, default false) — If true, return the full RDAP registrant contact. Default false → personal data dropped (GDPR), organization kept.

**Returns:** domain, registered, risk_score (0-100), risk_level (low|medium|elevated|high), reasons[] (plain-English explanation of each risk signal), lifecycle{age_days, age_band, days_to_expiry, expiry_risk, recently_registered, renewal_status}, signals{registrar, nameserver_provider, dnssec, has_certificate, mail{mx,spf,dmarc}, structural_flags[], impersonation}, parked{}

**Example request body:**
```json
{
  "domain": "google.com",
  "check_parked": false
}
```

### POST /domain-risk/v1/age — 1 credit
Domain age + expiry-risk band + renewal status (lifecycle synthesis from RDAP dates — NOT a raw whois dump; use domain-intel.whois for that).

**Parameters:**
- `domain` (string, required) — A full domain to evaluate (e.g. example.com, secure-login.io). A bare host, full URL, leading www., or an IDN (münchen.de) are accepted and normalized to its registrable form.

**Returns:** domain, registered, created/expires/updated, age_days, age_years, age_band (very_new|new|young|established|mature), days_to_expiry, expiry_risk (expired|imminent|soon|ok), recently_registered, renewal_status

**Example request body:**
```json
{
  "domain": "github.com"
}
```

### POST /domain-risk/v1/parked — 1 credit
Detect whether a domain is parked or listed for sale. Checks parking nameserver signals and the domain's root page for for-sale phrases and marketplace redirect hosts (Sedo, Afternic, GoDaddy, etc.). Returns a confidence-scored verdict: parked, for_sale, or actively in use. Returns 'unknown' when the page cannot be read.

**Parameters:**
- `domain` (string, required) — A full domain to evaluate (e.g. example.com, secure-login.io). A bare host, full URL, leading www., or an IDN (münchen.de) are accepted and normalized to its registrable form.

**Returns:** domain, parked (bool|null), for_sale (bool), confidence (high|medium|low), signals[] (each parking signal found), http_status, note

**Example request body:**
```json
{
  "domain": "google.com"
}
```

### POST /domain-risk/v1/typosquat — 1 credit
Generate a brand's lookalike domains across 16 permutation families (meets/exceeds dnstwist; incl IDN homoglyph/homograph) then report which are ACTUALLY REGISTERED + their risk — the brand-protection product.

**Parameters:**
- `domain` (string, required) — A full domain to evaluate (e.g. example.com, secure-login.io). A bare host, full URL, leading www., or an IDN (münchen.de) are accepted and normalized to its registrable form.
- `families` (array, optional) — Which typosquat permutation families to generate (comma-separated or array). Defaults to ALL 16 (meets/exceeds dnstwist): omission, repetition, transposition, replacement, insertion, vowel_swap, homoglyph, bitsquatting, hyphenation, addition, subdomain, tld_swap, combosquat, plural, homophones, various. Unknown names are ignored. [one of: omission, repetition, transposition, replacement, insertion, vowel_swap, homoglyph, bitsquatting, hyphenation, addition, subdomain, tld_swap, combosquat, plural, homophones, various]
- `keywords` (array, optional) — Additional keywords to include in the combosquat permutation family (e.g. your product name or campaign terms like 'checkout', 'wallet'). Combined with the built-in phishing keyword set (login, secure, verify…).
- `check_registered` (boolean, optional, default true) — If true (default), RDAP/DoH-check which generated lookalikes are actually registered (capped at 120 checks). False → return candidates only.

**Returns:** brand, generated, checked, registered_count, high_risk_count, registered[] (domain, family, risk, method; high-risk first), by_family{}, families[], note

**Example request body:**
```json
{
  "domain": "paypal.com",
  "families": "homoglyph,replacement,omission"
}
```

### POST /domain-risk/v1/reputation — 1 credit
Registrar / nameserver / age / mail-hygiene (SPF·DMARC·DNSSEC) trust signals → a 0-100 reputation_score + trust_level. Reputation is a positive-trust lens (vs assess's risk lens).

**Parameters:**
- `domain` (string, required) — A full domain to evaluate (e.g. example.com, secure-login.io). A bare host, full URL, leading www., or an IDN (münchen.de) are accepted and normalized to its registrable form.

**Returns:** domain, registered, reputation_score (0-100), trust_level (high|medium|low), registrar, nameserver_provider, dnssec, age_years, mail{mx,spf,dmarc}, impersonation, signals[]

**Example request body:**
```json
{
  "domain": "github.com"
}
```

### POST /domain-risk/v1/batch — 1 credit
Risk-assess up to 50 domains in one call (RDAP + DNS + email hygiene scoring, no per-domain parked-page probe). Returns a risk verdict per domain plus a combined high-risk list — ideal for bulk fraud screening.

**Parameters:**
- `domains` (array, required) — A list of full domains to risk-assess at once (comma-separated string or array). Capped at 50; invalid entries reported under 'invalid'.

**Returns:** results[] (per-domain risk verdict), high_risk[], high_risk_count, checked, invalid[] (rejected inputs)

**Example request body:**
```json
{
  "domains": "google.com,g00gle.com"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=domain-risk
- Human docs page: https://reefapi.com/docs/domain-risk
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt