SOA Record Lookup API: Query DNS SOA Records in JSON

Introduction

An SOA record lookup API lets applications retrieve the Start of Authority record for a DNS zone without parsing command-line DNS output. With WhoisJSON, you can query a domain and receive the SOA primary nameserver, hostmaster, serial number, refresh, retry, expire and minimum TTL fields as structured JSON.

This guide shows how to query SOA records with GET /api/v1/nslookup, interpret the returned fields, and use the SOA serial number to detect DNS zone updates before running a full DNS record comparison through the documented DNS Lookup API.

What Is an SOA Record?

SOA means Start of Authority. The record identifies administrative and synchronization information for a DNS zone: its primary nameserver, the responsible hostmaster value, a serial number, and timers used by secondary authoritative servers.

This article focuses on SOA interpretation and zone-change detection. For a general overview of every returned record type, use the DNS Lookup API guide.

Query an SOA Record 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 documented SOA object contains seven fields. Integrations should use these exact property names and should tolerate a missing SOA object when a lookup cannot return authoritative zone metadata.

{
  "SOA": {
    "nsname": "fish.ns.cloudflare.com",
    "hostmaster": "dns.cloudflare.com",
    "serial": 2287007851,
    "refresh": 10000,
    "retry": 2400,
    "expire": 604800,
    "minttl": 3600
  }
}

SOA Fields Explained

How to Interpret the SOA Serial Number

The serial is a zone version, not a guaranteed timestamp. Some operators use a date-based format such as YYYYMMDDnn, while others use a simple counter or another provider-managed value. Your monitoring logic should compare values rather than assume one formatting convention.

Python Example: Detect a Zone Update

Store the previous SOA snapshot with your domain inventory. On the next run, compare the serial and report the timing fields needed for investigation.

import requests

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


def get_soa(domain: str) -> dict | None:
    response = requests.get(
        f"{BASE_URL}/nslookup",
        headers={"Authorization": f"TOKEN={API_KEY}"},
        params={"domain": domain},
        timeout=10,
    )
    response.raise_for_status()
    return response.json().get("SOA")


def compare_soa(previous: dict | None, current: dict | None) -> dict:
    if current is None:
        return {"status": "soa_missing", "changed": None}
    if previous is None:
        return {"status": "baseline_created", "changed": None, "soa": current}

    changed = previous.get("serial") != current.get("serial")
    return {
        "status": "zone_updated" if changed else "unchanged",
        "changed": changed,
        "previousSerial": previous.get("serial"),
        "currentSerial": current.get("serial"),
        "primaryNameserver": current.get("nsname"),
        "refresh": current.get("refresh"),
        "retry": current.get("retry"),
        "expire": current.get("expire"),
        "minimumTtl": current.get("minttl"),
    }


previous = {"serial": 2287007850}
print(compare_soa(previous, get_soa("example.com")))

A production job should persist the baseline only after a successful response and handle 429 or transient 5xx responses with bounded backoff. See the API rate limits and retries guide for reusable patterns.

Node.js Example: Monitor Multiple Domains

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

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

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

  const data = await response.json();
  return data.SOA ?? null;
}

async function checkDomain(domain, previousSerial) {
  const soa = await getSoa(domain);
  if (!soa) {
    return { domain, status: "soa_missing", changed: null };
  }

  return {
    domain,
    status:
      previousSerial == null
        ? "baseline_created"
        : soa.serial !== previousSerial
          ? "zone_updated"
          : "unchanged",
    changed:
      previousSerial == null
        ? null
        : soa.serial !== previousSerial,
    previousSerial,
    currentSerial: soa.serial,
    primaryNameserver: soa.nsname,
  };
}

checkDomain("example.com", 2287007850)
  .then(console.log)
  .catch(console.error);

For a large portfolio, use controlled concurrency instead of launching every request at once. Keep failures isolated per domain so one timeout does not discard the complete monitoring run.

SOA Monitoring vs Full DNS Diffing

An SOA serial answers a narrow question: did the zone version change? It does not identify the modified record. A practical workflow uses the serial as a trigger and the complete DNS response as evidence.

1. Fetch the current SOA object and preserve lookup failures separately.
2. Compare the current serial with the last successful baseline.
3. When the serial changes, compare the DNS fields that matter to your system, such as NS, A, AAAA, MX, TXT, CAA or DMARC.
4. Classify expected migrations separately from unexplained configuration drift.
5. Store the new baseline only after the comparison and alerting step succeeds.

This pattern fits naturally into a domain portfolio management workflow where expiry, registrar, DNS and SSL state are reviewed together.

Common SOA Lookup API Use Cases

• DNS migration verification: record the new primary nameserver and establish a fresh serial baseline after an approved provider change.
• Configuration drift detection: trigger a record-level comparison when an unplanned serial change appears.
• Domain portfolio audits: inventory SOA ownership and timing values across customer or company domains.
• Incident response: correlate an SOA change with unexpected NS, MX, TXT or A-record changes.
• DNS operations reporting: expose zone metadata in a dashboard without parsing command-line output.

What an SOA Lookup Cannot Prove

FAQ

Conclusion

An SOA record lookup API turns zone metadata into JSON that applications can inventory and compare. The serial is the most useful change signal, while nsname, refresh, retry, expire and minttl provide operational context.

Keep the workflow precise: use the SOA serial to detect that a zone changed, then compare the DNS records that matter to determine what changed. This avoids confusing a zone version with a complete DNS audit.