Nameserver Monitoring API: Detect DNS Delegation Changes in JSON

Introduction

Nameserver changes are one of the highest-impact DNS events a domain operations team can monitor. When authoritative nameservers move, the whole zone can move with them: web records, email routing, verification TXT records, CAA policy, and subdomain behavior.

WhoisJSON does not expose a dedicated nameserver-only endpoint. The precise workflow uses the documented GET /api/v1/nslookup endpoint to read active NS records, then optionally compares those values with nameserver data returned by GET /api/v1/whois when WHOIS/RDAP data is available.

This article shows how to build that workflow, store a baseline, alert on unexpected delegation changes, and connect nameserver monitoring to a broader domain portfolio management process.

What Is a Nameserver Monitoring API?

A nameserver monitoring API is a workflow that queries authoritative DNS delegation data on a schedule, stores the expected nameserver set, and reports when the current set differs from the baseline.

In practice, nameserver monitoring is less about a single field and more about control. If a critical domain suddenly moves from an expected provider to an unknown provider, the team needs to know before customers experience broken DNS, failed email delivery, or an account takeover incident.

Why Nameserver Changes Matter

NS records define which servers are authoritative for a DNS zone. A normal change can be part of a planned migration. An unexpected change can indicate misconfiguration, registrar account compromise, vendor offboarding mistakes, or a forgotten domain moving outside the current operating model.

Which WhoisJSON Fields to Use

The documented DNS Lookup API and WHOIS API expose complementary nameserver signals.

Query NS Records in JSON

Authenticate with Authorization: TOKEN=YOUR_API_KEY and pass the root domain in the query string.

curl "https://whoisjson.com/api/v1/nslookup?domain=example.com" \
  -H "Authorization: TOKEN=YOUR_API_KEY"

The DNS response can include standard DNS records in one object. For nameserver monitoring, the core field is the NS array.

{
  "NS": [
    "a.iana-servers.net",
    "b.iana-servers.net"
  ],
  "SOA": {
    "nsname": "ns.icann.org",
    "hostmaster": "noc.dns.icann.org",
    "serial": 2024021764,
    "refresh": 7200,
    "retry": 3600,
    "expire": 1209600,
    "minttl": 3600
  }
}

Compare DNS NS Records with WHOIS/RDAP Nameservers

Live DNS and WHOIS/RDAP nameserver fields answer related but not identical questions. DNS NS records show the currently returned delegation data. WHOIS/RDAP nameservers show registration-side nameserver data when the upstream source provides it.

Query /whois when you want registration context, including the nameserver array and RDAP nsAnalysis object when available.

curl "https://whoisjson.com/api/v1/whois?domain=example.com" \
  -H "Authorization: TOKEN=YOUR_API_KEY"

{
  "nameserver": [
    "a.iana-servers.net",
    "b.iana-servers.net"
  ],
  "nsAnalysis": {
    "count": 2,
    "list": [
      "a.iana-servers.net",
      "b.iana-servers.net"
    ],
    "detectedProviders": [],
    "detectedProviderCount": 0,
    "uniqueNsDomains": 1,
    "mixedInfrastructure": false,
    "singleInfrastructure": true,
    "selfHosted": false
  }
}

Treat differences as investigation signals, not automatic verdicts. A registry update, DNS propagation window, provider migration, or upstream source difference can create temporary mismatch.

Python Example: Alert on NS Changes

Store normalized nameservers in your inventory. On each scheduled run, fetch the current NS array, compare sets, and only alert when the set changed.

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://whoisjson.com/api/v1"
HEADERS = {"Authorization": f"TOKEN={API_KEY}"}


def normalize_ns(values):
    return sorted({
        value.rstrip(".").lower()
        for value in values or []
        if isinstance(value, str) and value.strip()
    })


def get_dns_nameservers(domain):
    response = requests.get(
        f"{BASE_URL}/nslookup",
        headers=HEADERS,
        params={"domain": domain},
        timeout=10,
    )
    response.raise_for_status()
    return normalize_ns(response.json().get("NS", []))


def compare_nameservers(domain, previous_ns):
    current_ns = get_dns_nameservers(domain)
    previous = normalize_ns(previous_ns)

    added = sorted(set(current_ns) - set(previous))
    removed = sorted(set(previous) - set(current_ns))

    return {
        "domain": domain,
        "changed": bool(added or removed),
        "previous": previous,
        "current": current_ns,
        "added": added,
        "removed": removed,
    }


baseline = ["a.iana-servers.net", "b.iana-servers.net"]
print(compare_nameservers("example.com", baseline))

Production jobs should persist a new baseline only after a successful response and handle 429 or transient 5xx errors with bounded backoff. See the rate limits and retries guide for retry patterns.

Node.js Example: Compare DNS and WHOIS Nameservers

This example calls both documented endpoints and reports whether live DNS nameservers differ from WHOIS/RDAP nameservers.

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://whoisjson.com/api/v1";

function normalizeNs(values = []) {
  return [...new Set(
    values
      .filter((value) => typeof value === "string")
      .map((value) => value.trim().replace(/\.$/, "").toLowerCase())
      .filter(Boolean)
  )].sort();
}

async function getJson(path, domain) {
  const url = new URL(`${BASE_URL}/${path}`);
  url.searchParams.set("domain", domain);

  const response = await fetch(url, {
    headers: { Authorization: `TOKEN=${API_KEY}` },
  });
  if (!response.ok) {
    throw new Error(`${path} failed: ${response.status}`);
  }
  return response.json();
}

async function compareDelegation(domain) {
  const [dns, whois] = await Promise.all([
    getJson("nslookup", domain),
    getJson("whois", domain),
  ]);

  const dnsNs = normalizeNs(dns.NS);
  const whoisNs = normalizeNs(whois.nameserver);

  return {
    domain,
    dnsNameservers: dnsNs,
    whoisNameservers: whoisNs,
    mismatch:
      dnsNs.length > 0 &&
      whoisNs.length > 0 &&
      dnsNs.join("|") !== whoisNs.join("|"),
    rdapAnalysis: whois.nsAnalysis ?? null,
  };
}

compareDelegation("example.com")
  .then(console.log)
  .catch(console.error);

Operational Workflow for NS Monitoring

1. Build an inventory of critical domains: website, login, payment, email, API, SSO, redirects and customer-facing product domains.
2. Query each domain with /nslookup and store the normalized NS array as the baseline.
3. Add the expected DNS provider or expected nameserver suffix to your portfolio record.
4. On every refresh, compare the current NS set with the baseline.
5. If the set changed, query /whois for registrar/RDAP context and nsAnalysis when available.
6. Check the SOA.serial and compare other DNS records to understand whether the zone changed beyond delegation.
7. Route expected migrations to low-noise reporting and unexpected changes to incident review.

The SOA record lookup API guide is a useful companion when you want a zone-level change trigger before comparing record arrays.

Risk Signals to Track

Limits and Non-Goals

Keep the implementation honest and explicit about what the documented endpoints do and do not provide.

• WhoisJSON does not expose a dedicated nameserver-only endpoint; use /nslookup and read NS.
• The workflow does not perform DNS zone transfers. There is no AXFR or IXFR operation.
• The workflow does not provide historical DNS by itself. Store baselines in your application or use monitoring where change history is needed.
• A single response is not a global DNS propagation report across every resolver or region.
• Provider detection in nsAnalysis is informational and depends on pattern matching when RDAP data is available.
• This guide does not use reverse IP or reverse WHOIS workflows.

FAQ

Conclusion

Nameserver monitoring is a small workflow with a large operational payoff. If a domain's authoritative delegation changes unexpectedly, the business needs to know quickly because every DNS-dependent service can be affected.

The safe implementation is straightforward: read NS records from /nslookup, normalize and compare them against a baseline, enrich suspicious changes with /whois nameserver data and nsAnalysis when available, then investigate alongside SOA, MX, TXT, SSL and business ownership context.