Migrating from v3 to v4: API v4

Legacy v3 stays available until at least 21 January 2027 for accounts that used it before v4's launch on 23 October 2026. New accounts use v4. Your existing API key works with v4, so nothing needs re-provisioning.

The minimum migration is one line: change /api/v3 to /api/v4/categorize, and move the domain from a query parameter into a JSON body.

At a glance

Legacy v3 v4
Hostname website-categorization.whoisxmlapi.com unchanged
Endpoint GET /api/v3?apiKey=…&domainName=… POST /api/v4/categorize — POST only; a GET returns 405
Auth apiKey query parameter apiKey query parameter — the same key
Domain field domainName (query) domain (JSON body)
Taxonomy IAB Content Taxonomy v3, numeric ids IAB Content Taxonomy v3.1, prefixed string ids, hierarchical
Categories Flat list of 8–17 matches A primary category plus up to 2 alternatives (3 entries in total)
Removed fields — as, createdDate, websiteResponded are not returned
New fields — taxonomy_version, credits_charged, latency_ms, model, abstain, source
Opt-in blocks — Policy groups, brand safety, content purpose, domain status, OpenRTB, prediction sets

Your existing API key works with v4. Nothing needs re-provisioning.

Pricing

No existing subscription changes price mid-term, and renewals on or after 23 January 2027 are at the current price list. Your current credits keep their value, and renewals before that date stay at your current price.

New purchases follow the price list on the pricing page: one-time credit packs, which never expire, and monthly and yearly plans, with lower per-credit prices on larger packs and plans.

See Credits and limits for which calls consume a credit and which do not.

Before and after

# v3
r = httpx.get(
    "https://website-categorization.whoisxmlapi.com/api/v3",
    params={"apiKey": "YOUR_API_KEY", "domainName": "stackoverflow.com"},
).json()
name = r["categories"][0]["name"]   # "Technology & Computing"
asn = r["as"]["asn"]                # 13335

# v4 — POST only; apiKey stays a query param, the domain goes in the JSON body
r = httpx.post(
    "https://website-categorization.whoisxmlapi.com/api/v4/categorize",
    params={"apiKey": "YOUR_API_KEY"},
    json={"domain": "stackoverflow.com"},
).json()
name = r["primary_category"]["tier1"]   # "Technology & Computing"
path = r["primary_category"]["path"]    # "Technology & Computing > Computing > Programming Languages"
# ASN: a separate IP Geolocation API call
# v3
curl "https://website-categorization.whoisxmlapi.com/api/v3?apiKey=YOUR_API_KEY&domainName=stackoverflow.com"

# v4
curl -X POST "https://website-categorization.whoisxmlapi.com/api/v4/categorize?apiKey=YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domain": "stackoverflow.com"}'

Field mapping

v3 v4 Note
domainName domain Rename. Update anything reading response["domainName"].
categories[].id (int 596) categories[].id (string "IAB-596") Type change. Convert a v3 id with f"IAB-{id}" if you need to compare.
categories[].name (flat string) categories[].path plus tier1…tier4 Structural change. path is the joined string; the tier fields give each level.
categories[] (8–17 entries) categories[] (1–3) plus primary_category Semantic change. Use primary_category as your default.
as (ASN data) removed Use the WhoisXML IP Geolocation API directly.
createdDate (WHOIS) removed Use the WhoisXML WHOIS API directly.
websiteResponded (boolean) removed See abstain and include_status below.
— taxonomy_version Which taxonomy produced the result.
— credits_charged What the call cost. Easier reconciliation.
— latency_ms Server-internal processing time.
— model Which classification path answered.
— abstain Advisory signal: no real business purpose, or too little text to judge.
— source Provenance and freshness.
— error Per-request detail when a response is partial.

The four breaking changes

  1. POST, not GET. A GET to /api/v4/categorize returns 405. The domain moves into the JSON body; apiKey stays a query parameter.
  2. Fewer categories. v3 returned 8–17 loosely matching categories; v4 returns at most 3, the first of which is the primary. If you relied on categories[0], use primary_category.
  3. Different taxonomy. IAB v3.1 identifiers are prefixed strings, and some names differ from v3. Re-check any hard-coded category strings or ids.
  4. Three fields are gone. as, createdDate and websiteResponded are not in the v4 response. ASN and WHOIS data come from their own WhoisXML APIs; for "did the site respond", request include_status=true and read domain_status.

Replacing websiteResponded

There is no single boolean equivalent, because v4 draws a finer distinction.

  • abstain.is_abstain: true — an advisory flag: the page we classified reads as parked or for sale or was too short to judge, or the domain is on our list of ad-technology, DNS, CDN and cloud-hosting zones. It is never judged from domain_status, which is what tells you a domain is parked or dead. It does not clear categories; read credits_charged for what the call cost.
  • domain_status blocked, unreachable or error (with include_status=true) — we tried to read the site today and could not (anti-bot protection, no answer, or a server error). Such a result carries no category: categories is empty, primary_category is null, and the call is not billed. A domain answered without a read — from the curated list, a domain-name rule or the cache — keeps its category. From the 2 October 2026 update v4 no longer serves the legacy v3 label in its place, so source.is_historical_fallback is always false.
  • include_status=true gives you the full picture — domain_status distinguishes parked, inactive, expired, newly_registered, unreachable, blocked, suppressed and error. See Domain-status fields.

What v4 adds

  • A hierarchical taxonomy. tier1 to tier4 lets you decide at any level of granularity without parsing strings.
  • IAB v3.1, the taxonomy most ad-tech and brand-safety platforms have moved to.
  • Policy groups — 47 filtering groups you can write block rules against, instead of reconstructing the mapping from the tree yourself. See Policy pack.
  • Brand safety — an opt-in block with what our brand-safety filters measured on each result. See the Safety section of Output format.
  • Content purpose — an opt-in block that marks news sites with IAB Content Purpose = News, next to the unchanged topic. See Output format.
  • Domain-status fields — tell a live site from a parked or dead one.
  • OpenRTB output — an AdCOM-shaped projection you lift straight into a bid request.
  • Calibrated prediction sets — an opt-in set carrying an approximate coverage guarantee.
  • Bulk and async jobs — up to 100 domains synchronously, up to 10,000 as a background job.
  • Billing transparency — credits_charged on every categorization response.
  • Idempotent retries — with an Idempotency-Key header, a retry of a request that was already billed normally charges credits_charged: 0.

Of the response blocks in that list, all but the taxonomy are opt-in: policy groups, brand safety, content purpose and domain status are absent unless requested, while OpenRTB and prediction sets are present as null until requested. Adopting v4 does not change the shape of your responses until you ask it to.

How long legacy v3 stays available

  • 23 October 2026: v4 launches. From that day, legacy v3 serves only accounts that used it before 23 October. New accounts use v4.
  • Until at least 21 January 2027: legacy v3 stays available for those accounts.
  • After that: legacy v3 is switched off. The date is not set yet.

Move your integration to v4 before legacy v3 is switched off, using the steps on this page. New product features ship to v4 only.

If you need help with your migration, contact support.

Checking your migration

Send a sample of the domains you look up today to v4 and compare the answers with the v3 answers you already hold. Your existing API key works with v4, so there is nothing to provision.

Worth auditing first: any business logic keyed on specific v3 category strings or numeric ids rather than on the tier hierarchy. Those are the rules most likely to need adjusting.

Support

Email support@whoisxmlapi.com with the subject prefix [v4 migration] for anything migration-specific.