API Documentation

Integrate NVZS domain analysis into your own tools with a single HTTP request.

Authentication Endpoint Parameters Response Errors Tokens Examples

Authentication

Every request must include your API key as the api_key query parameter. You can find your key on your Dashboard.

GET https://nvzs.com/api?domain=example.com&api_key=YOUR_KEY

Keep your key private. Do not embed it in client-side JavaScript or public repositories. If compromised, contact support@nvzs.com to rotate it.

Endpoint

Method	URL	Description
GET	https://nvzs.com/api	Look up a domain and return full security metrics as JSON.

Query Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your API key from the Dashboard.
domain	string	Required	The domain to look up. Bare hostname only — no `https://` prefix or path. E.g. `example.com`, not `https://example.com/page`.
fresh	string	Optional	Set to `1` to force a live re-scan instead of returning cached data. Costs 1 token. Omit (or any other value) to use the cache for free.

Response Format

All responses are JSON. Successful responses use HTTP 200. The top-level fields are documented below, followed by the full example.

Top-level fields

Field	Type	Description
domain	`string`	The normalised domain name that was looked up.
nvz_score	`int \| null`	0–100 composite security score. null if not yet calculated.
scanned_at	`string`	UTC timestamp of when this result was last scanned.
from_cache	`boolean`	true if this result was served from cache (no token deducted).
domain_registration_date	`string \| null`	Registration date from public WHOIS data.
domain_age	`string \| null`	Human-readable domain age (e.g. "7 years").
ssl	`object`	SSL/TLS details — see sub-fields below.
server	`object`	Server location, IP, hostname, and software type.
technology	`object`	Detected CMS/frameworks, analytics, page size, meta description.
security_headers	`object`	Key→value map of HTTP security headers. Value is "Not Found" if absent.
security_policies	`object`	security_txt and caa_policy presence.
email_security	`object`	DMARC record, MTA-STS, SMTP TLS Reporting, and detected email host.
open_graph	`object`	Open Graph meta tag values for social share previews.
sitemap	`object`	sitemap_url and url_count if a sitemap.xml was found.
domain_extensions	`object`	Availability of related TLDs — key is extension (e.g. "net"), value is "available" or "registered".
tokens_remaining	`int`	Your remaining token balance after this request.

ssl object fields

Field	Type	Description
status	`string`	Certificate type, e.g. "Domain Validated (DV)", "Extended Validation (EV)".
issuer	`string`	Certificate authority, e.g. "Let's Encrypt".
valid_from	`string`	Certificate start date.
valid_to	`string`	Certificate expiry date.

Full example response

{
  "domain":                   "example.com",
  "nvz_score":                82,
  "scanned_at":               "2025-03-15 14:22:10",
  "from_cache":               true,
  "domain_registration_date": "1995-08-14",
  "domain_age":               "29 years",

  "ssl": {
    "status":     "Domain Validated (DV)",
    "issuer":     "Let's Encrypt",
    "valid_from": "2025-01-01",
    "valid_to":   "2025-04-01"
  },

  "server": {
    "ip":       "93.184.216.34",
    "hostname": "93.184.216.34",
    "location": "United States",
    "type":     "ECS"
  },

  "technology": {
    "stack":            ["WordPress", "jQuery"],
    "google_analytics": "Enabled",
    "page_size":        "48 KB",
    "meta_description": "Example Domain — for illustrative use.",
    "favicon_url":      "https://example.com/favicon.ico",
    "ads_txt":          "Not Found"
  },

  "security_headers": {
    "Content-Security-Policy":   "default-src 'self'",
    "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
    "X-Content-Type-Options":    "nosniff",
    "X-Frame-Options":           "SAMEORIGIN",
    "X-XSS-Protection":          "Not Found",
    "Permissions-Policy":        "Not Found",
    "Referrer-Policy":           "same-origin"
  },

  "security_policies": {
    "security_txt": "Found",
    "caa_policy":   "Yes, CAA policy exists"
  },

  "email_security": {
    "email_host":         "Google Workspace",
    "dmarc_record":       "v=DMARC1; p=reject; rua=mailto:dmarc@example.com",
    "mta_sts_policy":     "version: STSv1\nmode: enforce",
    "smtp_tls_reporting": "v=TLSRPTv1; rua=mailto:tls@example.com"
  },

  "open_graph": {
    "og:title":       "Example Domain",
    "og:description": "This domain is for use in examples.",
    "og:image":       "https://example.com/og-image.png",
    "og:url":         "https://example.com"
  },

  "sitemap": {
    "sitemap_url": "https://example.com/sitemap.xml",
    "url_count":   42
  },

  "domain_extensions": {
    "com":  "registered",
    "net":  "registered",
    "org":  "registered",
    "xyz":  "available",
    "site": "available",
    "ca":   "available",
    "us":   "registered",
    "app":  "available"
  },

  "tokens_remaining": 47
}

Error Responses

Errors always return a JSON object with an error code and a human-readable message.

HTTP	`error` code	When it occurs
400	missing_domain	No domain parameter was provided.
400	invalid_domain	The domain parameter is not a valid hostname.
401	missing_api_key	No api_key parameter was provided.
401	invalid_api_key	The api_key does not match any account.
402	insufficient_tokens	Your token balance is 0. Upgrade at nvzs.com/pricing.
404	domain_not_found	The domain could not be resolved via DNS. Token is refunded.
405	method_not_allowed	A non-GET HTTP method was used.
500	server_error	An internal server error occurred during auth or DB access.
500	scan_error	An error occurred while running the scan. Token is refunded.
500	save_error	Scan completed but results could not be saved to the database.

Example error response:

{
  "error":   "insufficient_tokens",
  "message": "You have 0 API tokens remaining. Please upgrade your plan at nvzs.com/pricing."
}

Token Rules

Cached result

Domain already in our database. Returns instantly at no token cost.

First scan

Domain not in our database. Runs a full scan and costs 1 token.

Re-scan (fresh=1)

Forces a new live scan regardless of cache. Costs 1 token.

If a scan fails because the domain cannot be resolved, or due to a server error, the token is automatically refunded. Tokens are allocated per plan — see Pricing.

Rate Limits

Plan	Requests / minute	Monthly token cap
Free	10 / min	50
Pro	10 / min	1,000
Enterprise	Unlimited	Unlimited

Code Examples

# Cached lookup (free)
curl "https://nvzs.com/api?domain=example.com&api_key=YOUR_KEY"

# Force a fresh re-scan (1 token)
curl "https://nvzs.com/api?domain=example.com&api_key=YOUR_KEY&fresh=1"

const API_KEY = 'YOUR_KEY';

async function lookupDomain(domain, fresh = false) {
  const url = new URL('https://nvzs.com/api');
  url.searchParams.set('domain',  domain);
  url.searchParams.set('api_key', API_KEY);
  if (fresh) url.searchParams.set('fresh', '1');

  const res = await fetch(url);
  const data = await res.json();

  if (!res.ok) {
    throw new Error(`${data.error}: ${data.message}`);
  }
  return data;
}

// Example
lookupDomain('example.com')
  .then(data => console.log(`NVZ Score: ${data.nvz_score}`))
  .catch(err => console.error(err));

<?php
function nvzsLookup(string $domain, string $apiKey, bool $fresh = false): array {
    $url = 'https://nvzs.com/api?' . http_build_query(array_filter([
        'domain'  => $domain,
        'api_key' => $apiKey,
        'fresh'   => $fresh ? '1' : null,
    ]));

    $response = file_get_contents($url);
    if ($response === false) {
        throw new RuntimeException('Request failed');
    }

    $data = json_decode($response, true);
    if (isset($data['error'])) {
        throw new RuntimeException($data['error'] . ': ' . $data['message']);
    }
    return $data;
}

// Example
$result = nvzsLookup('example.com', 'YOUR_KEY');
echo 'NVZ Score: ' . $result['nvz_score'] . PHP_EOL;
echo 'SSL issuer: ' . $result['ssl']['issuer'] . PHP_EOL;

import requests

API_KEY = "YOUR_KEY"

def lookup_domain(domain: str, fresh: bool = False) -> dict:
    params = {"domain": domain, "api_key": API_KEY}
    if fresh:
        params["fresh"] = "1"

    r = requests.get("https://nvzs.com/api", params=params, timeout=60)
    data = r.json()

    if not r.ok:
        raise ValueError(f"{data['error']}: {data['message']}")
    return data

# Example
result = lookup_domain("example.com")
print(f"NVZ Score:  {result['nvz_score']}")
print(f"SSL status: {result['ssl']['status']}")
print(f"DMARC:      {result['email_security']['dmarc_record']}")

Ready to start building?

Get your free API key Compare plans