BKNS Whois API

REST API for WHOIS lookup and domain availability checking.
Supports 1,260+ TLDs · .vn data from official VNNIC · Latency < 200ms

All requests over HTTPS. JSON response, UTF-8 encoding.

Authentication

Attach your API key to the X-API-Key header in every request. Missing or invalid key → HTTP 401.

GET /api/v1/whois?domain=bkns.vn
X-API-Key: bkns_dmo_2376da23bd44858c8390aeeb93065404d21ede1ba2c5d59c0cffc33d6e83c2dd
Content-Type: application/json

X-API-Key: bkns_dmo_2376da23bd44858c8390aeeb93065404d21ede1ba2c5d59c0cffc33d6e83c2dd

Rate Limits

Request limits per tier. Exceeding the threshold → 429 Too Many Requests with a Retry-After header.

X-RateLimit-Limit:     300
X-RateLimit-Remaining:  0
X-RateLimit-Reset:      1711234567
Retry-After:           15

Error codes

Error envelope: v1 vs v2

v1 (legacy) returns a flat error body with errorCode. v2 (standard) wraps the error in an error object with a BKNS-WHOIS-NNN code, bilingual message, and a correlation_id for tracing.

{
  "errorCode": "INVALID_DOMAIN",
  "message": "Invalid domain name",
  "statusCode": 400
}

v2 error code catalog — BKNS-WHOIS-001…014

Every v2 error carries a fixed BKNS-WHOIS-NNN code with its HTTP status. The error.details.legacyCode field (when present) is the equivalent v1 code, used as a bridge during the transition — it will be removed once every consumer reads error.code.

API v2 & Migration

BKNS Whois API now serves two versions in parallel on the same gateway. Pick the version that fits your integration — there is no mandatory cutover.

v1 → v2 migration guide

1. 1

   Step 1 — Change the base URL

   Change /api/v1 to /api/v2. Success response bodies are 100% identical — same fields, same flat structure, no success/data wrapper — no code change needed for the success path.

2. 2

   Step 2 — Update error handling

   Read error.code (e.g. BKNS-WHOIS-001) instead of the top-level errorCode, and error.message / error.messageEn instead of message. Use the code catalog table in the Error codes section to map; during the transition, error.details.legacyCode still carries the old code so you can match either.

3. 3

   Step 3 — Strict requests

   v2 rejects any unknown query/body field from the very first request — a 400 BKNS-WHOIS-002, with no grace window. Send only documented parameters: domain, raw, bypass_cache (bulk: domains). Remove any stray parameters before switching to v2.

4. 4

   Step 4 — Nothing else changes

   Authentication (X-API-Key), tier-based rate limits, and the status values (pending | registered | available | reserved | auction) are unchanged between v1 and v2. v2 shares the same rate-limit budget as v1 — switching surfaces does not reset your quota.

GETWHOIS Lookup

Full WHOIS lookup: owner, registrar, creation/expiry dates, nameservers, EPP status.

Also available at /api/v2/whois with the standard error envelope (v2) — see the v1 → v2 migration guide

{
  "domain": "bkns.vn",
  "tld": "vn",
  "status": "registered",
  "cached": true,
  "cacheTtlRemaining": null,
  "data": {
    "registrant": {
      "name": "Công ty Cổ phần Giải pháp Mạng Bạch Kim"
    },
    "registrar": {
      "name": "Công ty cổ phần giải pháp mạng Bạch Kim"
    },
    "nameservers": ["ns1.bkdns.vn", "ns2.bkdns.vn", "ns3.bkdns.vn"],
    "dates": {
      "created": "2010-06-24T17:00:00.000Z",
      "updated": null,
      "expiry": "2030-06-24T17:00:00.000Z",
      "renewalDeadline": null
    },
    "domainStatus": ["clientTransferProhibited"],
    "dnssec": false
  }
}

GETDomain Check

Quickly check whether a domain is available. Faster than WHOIS as it only returns status.

Also available at /api/v2/domain/check with the standard error envelope (v2) — see the v1 → v2 migration guide

{
  "domain": "example-notexist.vn",
  "tld": "vn",
  "available": true,
  "premium": false,
  "cached": false
}

// congchung.vn — reserved
{ "domain": "congchung.vn", "available": false, "reserved": true, "reservedBy": "Cục CNTT – Bộ Tư pháp" }

// bk.vn — auction-only (.vn 1–2 ký tự)
{ "domain": "bk.vn", "available": false, "auction": true }

POSTBulk WHOIS

Look up multiple domains in a single request. Maximum 20 domains/request. Requires Partner tier.

Note: Bulk WHOIS requires a Partner key — the demo key returns 403 on this endpoint.

Also available at /api/v2/whois/bulk with the standard error envelope (v2) — see the v1 → v2 migration guide

{
  "domains": ["bkns.vn", "google.com", "example.org"]
}

{
  "results": [
    { "domain": "bkns.vn",     "status": "registered", "data": { ... } },
    { "domain": "example.org", "status": "available" }
  ],
  "total": 3,
  "queryTime": 512
}

Response Schema

Full structure of the WHOIS response object.

Top-level fields

data object (registered only)

Supported TLDs

1,260+ TLD types including all ccTLDs, popular gTLDs, and new gTLDs.

Code samples

WHOIS Lookup

const domain = 'bkns.vn';
const apiKey = 'bkns_dmo_2376da23bd44858c8390aeeb93065404d21ede1ba2c5d59c0cffc33d6e83c2dd';

const res = await fetch(
  `https://whois.bkns.vn/api/v1/whois?domain=${domain}`,
  { headers: { 'X-API-Key': apiKey } }
);

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

// Always check status before accessing data.*
if (data.status === 'registered') {
  console.log('Registrar:', data.data.registrar.name);
  console.log('Expires: ', data.data.dates.expiry);
  console.log('Nameservers:', data.data.nameservers.join(', '));
} else {
  console.log('Domain is not registered.');
}

Handle 429 — Retry with backoff

async function whoisWithRetry(domain, apiKey, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(
      `https://whois.bkns.vn/api/v1/whois?domain=${domain}`,
      { headers: { 'X-API-Key': apiKey } }
    );
    if (res.status === 429) {
      const wait = Number(res.headers.get('Retry-After') ?? 5) * 1000;
      await new Promise(r => setTimeout(r, wait));
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  }
}

v2 example — endpoint & error envelope

The /api/v2/whois endpoint shares the same parameters as v1 (domain, raw, bypass_cache), but errors come back in the standard error envelope — see the Error codes section for the full catalog.

curl -s \
  "https://whois.bkns.vn/api/v2/whois?domain=bkns.vn" \
  -H "X-API-Key: bkns_dmo_2376da23bd44858c8390aeeb93065404d21ede1ba2c5d59c0cffc33d6e83c2dd" \
  | python3 -m json.tool

{
  "success": false,
  "error": {
    "code": "BKNS-WHOIS-001",
    "message": "Tên miền không hợp lệ",
    "messageEn": "Invalid domain name",
    "details": { "legacyCode": "INVALID_DOMAIN" },
    "correlation_id": "01J8Z3K9QW7M2P5RXT6VYB4NDA"
  }
}

Contact

Need technical support or want to register a Partner API key?