A WHOIS API in 2026 is not necessarily a wrapper around TCP port 43. DomScan's main domain registration endpoint is RDAP-first. It discovers the relevant registration service, requests current data, and converts the response into a normalized domain-focused shape. Traditional WHOIS remains a fallback for TLDs or upstream failures where it can add evidence. A DNS-only fallback is used in narrower failure cases and is labeled as heuristic. The source labels matter as much as the dates and registrar fields.
The change reflects the public registration data system. ICANN says gTLD registries and registrars have been required to provide RDAP, and most were no longer required to provide WHOIS after 28 January 2025, with listed exceptions for .com, .name, and .post. ICANN's Registration Data Policy became effective on 21 August 2025 and was updated on 12 May 2026. That policy governs ICANN-accredited registrars and contracted gTLD registry operators. Country-code registries set their own publication and access policies.
This guide documents the current DomScan contract rather than promising a universal set of fields. Registration services differ in coverage, policy, redaction, uptime, and error behavior. A response may contain registrar and lifecycle data but no public registrant contact. Another may be translated from traditional WHOIS. A DNS fallback may say only that the domain has active DNS. Code that treats every response as a full ownership record will fail technically and reach conclusions the data does not support.
WHOIS and RDAP are different protocols
RFC 3912 describes WHOIS as a TCP query and response protocol whose server listens on port 43. The client sends text and receives human-readable text. The protocol does not define a registration-data schema, a character-set negotiation mechanism, modern authentication, or a standard way to discover the correct server. Registry and registrar deployments added their own conventions over time, which is why traditional WHOIS parsing remains source-specific.
RDAP uses HTTP and JSON. RFC 7480 is the Internet Standard for HTTP usage. RFC 7482 originally defined query paths and RFC 7483 defined JSON responses; RFC 9082 and RFC 9083 replaced those two documents. RFC 9224 is not the RDAP protocol specification. It describes how a client finds the authoritative RDAP service and replaced the earlier bootstrap specification in RFC 7484.
DomScan uses the IANA bootstrap registries to route DNS, IPv4, IPv6, and autonomous system queries. The DNS bootstrap maps top-level domains to RDAP bases. The IP and ASN files map number ranges to Regional Internet Registry services. DomScan refreshes the DNS map through a scheduled process, stores it in D1, and retains a static map for continuity. IANA bootstrap coverage does not mean every server is equally reliable or that every TLD publishes the same fields.
Choose the endpoint by the response you need
- `GET /v1/whois?domain=example.com` returns normalized domain registration data and uses a cache-first RDAP path. It costs 2 credits.
- `GET /v2/whois?domain=example.com` fetches RDAP and traditional WHOIS in parallel, then merges available enrichment. It also costs 2 credits.
- `POST /v1/whois/bulk` accepts an array of 1 to 20 domains. API-key billing is 2 credits per submitted domain.
- `GET /v1/rdap` returns a wrapper around raw or source-translated registration data for a domain, IP network, or autonomous system number. It costs 2 credits.
- `GET /v1/whois/history?domain=example.com` reads DomScan's normalized observation log. It costs 2 credits and does not trigger a new snapshot.
GET /v1/whois: normalized and cache-first
The v1 endpoint validates and normalizes the domain, then checks a dedicated WHOIS KV entry. A cached normalized RDAP result can be reused for up to 30 minutes. The response tells you when that path was used through `meta.cache: "hit"` and an `edge_summary` that includes `cache` in `data_sources`. A cache hit does not create a WHOIS History snapshot. The HTTP response also permits public caching for five minutes, while an RDAP not-found result is returned with a shorter one-minute public cache directive and is not written to the 30-minute KV entry.
On a cache miss, v1 queries RDAP and normalizes events, statuses, nameservers, entities, DNSSEC, transfer-lock signals, and derived date calculations. If RDAP fails, DomScan tries traditional WHOIS through the Edge Relay. A traditional response can include parsed fields and `raw_whois`, with `meta.data_source` set to `whois`. Some unreachable or unsupported registration paths fall back to DNS activity. Those responses carry null registration fields, a `dns_status` object, source metadata, and a warning because DNS activity is not equivalent to registration data.
curl -sS \
-H "X-API-Key: $DOMSCAN_API_KEY" \
"https://domscan.net/v1/whois?domain=example.com"{
"domain": "example.com",
"registrar": "RESERVED-Internet Assigned Numbers Authority",
"created_date": "1995-08-14T04:00:00Z",
"expiry_date": "2026-08-13T04:00:00Z",
"status": [
"client delete prohibited",
"client transfer prohibited",
"client update prohibited"
],
"nameservers": [
"elliott.ns.cloudflare.com",
"hera.ns.cloudflare.com"
],
"registered": true,
"edge_summary": {
"data_sources": ["rdap"],
"authoritative_source": "rdap",
"raw_whois_available": false
},
"meta": {
"data_source": "rdap"
}
}The example is a snapshot, not a fixture. Dates, statuses, nameservers, and source paths can change. Consumers should parse fields instead of comparing the entire response to a saved JSON blob. Check `registered`, `available`, `edge_summary.data_sources`, `edge_summary.authoritative_source`, and `meta` before interpreting the normalized fields. The source label describes how DomScan produced the response. It does not make a DNS heuristic or cached copy an authoritative legal record.
GET /v2/whois: RDAP plus traditional WHOIS evidence
The v2 endpoint runs the RDAP and traditional WHOIS requests in parallel rather than reading the v1 normalized KV entry first. It begins with the normalized RDAP result, then adds traditional abuse contact, registry domain ID, registrar WHOIS server, nameserver addresses, contacts, or raw text when the traditional source actually provides them. It records the source set in `meta.data_sources` and the `edge_summary`. On the live `example.com` check used for this article, v2 reported both `rdap` and `whois`, exposed raw WHOIS, and named `whois.iana.org` as the traditional server.
More source data does not guarantee more personal data. Traditional WHOIS can be redacted, unavailable, or skipped for TLDs where it is slow or unhelpful. When RDAP fails but traditional parsing succeeds, v2 can return a traditional-only normalized response. If neither registration source works and the failure qualifies for DNS fallback, the result is explicitly limited. v2 writes the normalized RDAP core to the same 30-minute KV area used by v1 and can create a history snapshot when the RDAP-backed lookup qualifies.
curl -sS \
-H "X-API-Key: $DOMSCAN_API_KEY" \
"https://domscan.net/v2/whois?domain=example.com" | \
jq '{domain, registrar, sources: .meta.data_sources, raw: .edge_summary.raw_whois_available, abuse: .edge_summary.abuse_contact_available}'POST /v1/whois/bulk: bounded portfolio lookup
Bulk WHOIS accepts a `domains` array with at least one and no more than 20 entries. The cost is 2 credits for each submitted domain, so ten domains cost 20 credits. The endpoint processes items with bounded concurrency and returns `total`, `successful`, `failed`, overall `query_time_ms`, and a result entry for each input. An invalid domain or upstream failure can appear as an error inside one result while other domains succeed. Validate and deduplicate input before submission because billing is based on every submitted item, including failed results.
curl -sS -X POST \
-H "X-API-Key: $DOMSCAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains":["example.com","iana.org"]}' \
"https://domscan.net/v1/whois/bulk"Bulk results follow the same source hierarchy but are optimized for a short batch window. A registered domain normally carries normalized RDAP fields and an `edge_summary`. A traditional fallback identifies `whois` as its source. A DNS fallback sets `data_source: "dns"`, `confidence: "heuristic"`, and a warning code. The response allows five minutes of public caching. Bulk requests never create WHOIS History snapshots, even when an item succeeds through RDAP.
GET /v1/rdap: domain, IP, and autnum
The RDAP route accepts `query` and an optional `type` value of `domain`, `ip`, or `autnum`. Domain is the default. The `domain` query parameter is also accepted as an alias for a domain lookup. An IP address or ASN passed without `type` is rejected instead of being guessed, so use `type=ip&query=8.8.8.8` or `type=autnum&query=AS174`. IP input may be an address or CIDR. Autnum input accepts the `AS` prefix and normalizes the response query to the number.
curl -H "X-API-Key: $DOMSCAN_API_KEY" \
"https://domscan.net/v1/rdap?query=example.com"
curl -H "X-API-Key: $DOMSCAN_API_KEY" \
"https://domscan.net/v1/rdap?type=ip&query=8.8.8.8"
curl -H "X-API-Key: $DOMSCAN_API_KEY" \
"https://domscan.net/v1/rdap?type=autnum&query=AS174"The response wrapper contains `query`, `type`, `status`, the registration object in `rdap`, a typed `entity_summary` when available, and `lookup_summary`. A live query for `8.8.8.8` returned an `ip network` object covering `8.8.8.0` through `8.8.8.255`. A query for AS174 returned an `autnum` object with start and end value 174. These identify registered number resources and entities in the source record. They do not identify the user of a particular address or prove who originated traffic.
For a normal domain result, `lookup_summary.data_source` is `rdap`. Some TLD policies prefer traditional WHOIS; DomScan then translates parsed WHOIS into an RDAP-shaped domain object and labels the source `whois`. When domain RDAP is unreachable or rate limited, a successful DNS check can produce a 200 fallback with `rdap: null`, `data_source: "dns_fallback"`, and a warning. Normal RDAP success is fetched from the source path rather than the v1 WHOIS KV cache. The DNS fallback carries a one-minute public cache directive.
Null fields and redaction are normal
Do not build a schema that requires registrar, creation date, expiry date, every contact role, abuse email, and DNSSEC to be populated together. RDAP standardizes object structure, but policy and registry practice determine what is published. Events can be absent or named differently. A registry-level response and a registrar-level response can expose different entities. Traditional WHOIS parsing can also omit a field that appears under an unfamiliar label. Use nullable fields and empty arrays as first-class states, not parser failures by default.
The current ICANN Registration Data Policy covers publication and disclosure for gTLD registration data. Public contact values may be redacted or replaced with a pseudonymized address or communication form. Lawful disclosure follows a separate request process and applicable policy; a public DomScan call does not bypass it. ccTLD policy can differ. A returned registrant organization may name a privacy or proxy service, and an absent contact may reflect redaction rather than a missing registration.
DomScan's normalized `privacy.is_private` and `edge_summary.privacy_protected` values are detection signals. They look for privacy-service patterns and treat an RDAP response with entities but no usable contacts as likely redacted. That can be useful for triage, but it does not distinguish every privacy service from every policy redaction. The live `example.com` response, for example, marked privacy protection even though the domain is reserved by IANA. Preserve the underlying source fields before making a policy or investigative decision.
Handle errors and limits by category
A missing or invalid parameter returns a 400-class error. Missing or invalid API authentication returns 401. Insufficient credits returns 402 with the required and remaining credit context. Request throttling returns 429 and may include `Retry-After`. An unrecoverable RDAP path can return 503. Bulk processing also has per-item errors inside an otherwise successful top-level response. Log the HTTP status, `error.code`, request ID header when present, query, and source summary. Retrying every error as if it were a timeout wastes credits and can amplify an upstream incident.
DomScan applies request limits, and the upstream RDAP and WHOIS services enforce their own policies. Those values can change by deployment, plan, registry, source address, and upstream health. Do not hardcode a claim such as a fixed number of lookups per minute into an integration. Respect 429 responses and `Retry-After`, add exponential backoff with jitter for retryable failures, cap total attempts, and use bulk for groups of up to 20 domains. A protocol error, invalid domain, unsupported TLD, or insufficient-credit response needs correction rather than blind retry.
WHOIS History records observations, not worldwide history
A qualifying fresh, successful RDAP-backed `GET /v1/whois` or `GET /v2/whois` lookup can create at most one normalized snapshot for a domain on each UTC day. A v1 KV cache hit does not create one. Bulk requests do not create snapshots. Reading `GET /v1/whois/history` does not create a snapshot. Traditional WHOIS-only responses and DNS fallbacks do not create snapshots either. A v2 response that includes traditional enrichment can qualify when the normalized core is backed by a successful RDAP result.
Snapshots store registrar, registrar IANA ID, creation, update and expiry values, statuses, nameservers, DNSSEC, transfer-lock detection, and privacy or redaction detection. They do not store registrant identity or contact history. Change summaries compare the recorded snapshots and can report registrar, expiry, nameserver, status, DNSSEC, transfer-lock, or privacy-signal differences. `first_seen`, `last_seen`, `total_snapshots`, and the summary describe only the returned limit-scoped window, which defaults to 50 snapshots and accepts at most 100.
An observed change is not proof of a transfer or the exact time an upstream record changed. If DomScan saw one registrar on Monday and another on Thursday, the underlying change occurred somewhere between those observations. A temporary parser or source difference can also change a normalized field. Use registrar records, account audit logs, transfer notices, and legal documentation for attribution. WHOIS History is useful for identifying a period to investigate and for comparing recurring checks, not for reconstructing unobserved days.
Build the integration around provenance
Store the normalized fields your workflow needs, but keep `checked_at`, source metadata, query type, and the raw RDAP object or raw WHOIS text when your retention policy permits it. Derived values such as `domain_age_days`, `days_until_expiry`, transfer lock, and privacy detection should remain traceable to their observation. If a later lookup changes source from RDAP to DNS fallback, your system should lower confidence rather than overwrite a complete registration record with nulls and present the result as confirmed.
For portfolio work, use bulk requests in chunks of 20, validate each input, and treat each result independently. For investigations, prefer v1 when normalized current registration data is enough, v2 when traditional WHOIS evidence is worth the extra response size, and raw RDAP when you need the full domain, IP network, or autnum object. Domain Profile offers a focused normalized RDAP registration view. Use the dedicated DNS, certificate, hosting, and security endpoints when those separate questions matter. More fields are useful only when their source and limits survive the trip into your database.
The reliable stopping point is a source-aware record: what was queried, when DomScan checked it, which endpoint produced it, what the upstream source returned, which fields were absent, and whether any fallback was used. That is enough to automate expiry review, enrich a security alert, or compare portfolio state without pretending that public registration data reveals an owner it does not name.