BKNS Whois API

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

Base URLhttps://whois.bkns.vn/api/v1

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.

http

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

⚠Keep your API key secret. Do not embed in client-side JavaScript or mobile apps. Contact info@bkns.vn to get or rotate a key.

Rate Limits

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

Public

10 req/min

Lookup via UI. No API key needed.

Partner

300 req/min

Server-side integration. Contact us to get a key.

response headers

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

Error codes

200OK — SuccessProcess response normally

400Bad Request — Invalid domainValidate format before calling

401Unauthorized — Invalid or missing API keyCheck X-API-Key header

429Too Many Requests — Rate limit exceededWait per Retry-After header

500Internal Server ErrorRetry later, report if recurring

503Service Unavailable — Registry not respondingExponential backoff retry

GETWHOIS Lookup

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

GET/api/v1/whoisWHOIS Lookup

Parameter / Type / Description

Parameter	Type	Description
domain required	string	Domain to look up. Accepts ASCII (bkns.vn), punycode (xn--...), or Unicode IDN (münchen.de). Automatically normalizes to punycode.

Response

json · HTTP 200 · source: vnnic-relay

{
  "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
  }
}

ℹOnly for .vn: The data.registrant field is returned. International domains typically do not include registrant information.

GETDomain Check

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

GET/api/v1/domain/checkAvailability check

Parameter / Type / Description

Parameter	Type	Description
domain required	string	Domain to check. Accepts ASCII, punycode, or Unicode IDN. Automatically normalizes to punycode.

json · HTTP 200

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

POSTBulk WHOIS

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

POST/api/v1/whois/bulkBulk lookup

Request Body

json

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

Response

json · HTTP 200

{
  "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

domainstringDomain in ASCII/punycode form (canonical key). Example: "xn--mnchen-3ya.de"

idnDomainoptionalstring | undefinedUnicode display form of an IDN domain. Only present when the domain contains internationalized labels (xn--). Example: "münchen.de". Omitted for pure ASCII domains.

tldstringTLD of the domain: "vn", "net", "com"…

status"registered" | "available"registeredavailable

cachedbooleanWhether the response came from cache or a live query

dataoptionalobject | undefinedOnly present when status = "registered"

backendsTriedoptionalarray | undefinedBackends attempted, only present when cached = false

data object (registered only)

data.registrant.nameoptionalstring | undefinedOwner name. Only available for .vn domains

data.registrar.namestringRegistrar name

data.nameserversstring[]List of nameservers

data.dates.createdISO 8601 | nullDomain creation date

data.dates.expiryISO 8601 | nullDomain expiry date

data.dates.updatedISO 8601 | nullLast updated date

data.domainStatusstring[]EPP status codes: "clientTransferProhibited", "ok"…

data.dnssecbooleanDNSSEC enabled

Supported TLDs

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

✓Domains .vn, .com.vn, .net.vn, .org.vn, .edu.vn, .gov.vn are queried directly via official VNNIC — most accurate and fastest data. Backend: vnnic-relay, latency ~145ms.

Code samples

WHOIS Lookup

javascript · Node.js 18+

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

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

javascript

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();
  }
}

Contact

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