API for businesses

who.com.vn API documentation

Bring domain lookups, expiry dates, lifecycle milestones and DNS records into your own systems. Same data and rules as the who.com.vn site, as JSON.

Request API access Download OpenAPI (JSON)

Overview

Every endpoint uses HTTPS and answers UTF-8 JSON (bulk lookup answers NDJSON and export answers an Excel/CSV file). Dates are Vietnam calendar dates (YYYY-MM-DD); timestamps are ISO 8601 in UTC.

Add lang=vi or lang=en to the URL to choose the language of error messages and lifecycle labels; by default it follows the Accept-Language header.

Base URL: https://who.com.vn/api/v1

GET/api/v1/whois— Domain lookup (whois)
GET/api/v1/lifecycle— Domain lifecycle
GET/api/v1/dns— DNS records
POST/api/v1/whois/bulk— Bulk lookup
POST/api/v1/whois/export— Export to Excel / CSV

Authentication

HVN issues each business an API key (who_live_…) once its request is approved. The key is shown only once when issued; HVN stores only a hash and cannot show it again — if it is lost, HVN issues a new one.

Send the key in the Authorization header as a Bearer token:

Authorization

Authorization: Bearer who_live_••••••••••••••••••••••••••••••••

Or use the X-API-Key header:

X-API-Key

X-API-Key: who_live_••••••••••••••••••••••••••••••••

Send the key in a header only. A key in the URL (query string) is refused with key_in_query, because URLs end up in logs and Referer headers.
Never embed the key in code that runs in a browser or a mobile app. Call the API from your server and pass the results on to your users.
Each key can only use the scopes it was granted: whois, lifecycle, dns, bulk, export.
A wrong, revoked or expired key gets 401 invalid_api_key — it never falls back to the shared limits. If a key may have leaked, ask HVN to rotate it: the old key stops working at once.

Without a key the API still answers, sharing the per-IP limits of the website's visitors (see Limits).

Endpoints

Domain lookup (whois)

GET/api/v1/whois· Key scope: whois

Status, holder (organisations), registrar, registration and expiry dates, name servers, EPP status and the raw record of one domain.

Query parameters

Parameter	Required	Description
`domain`	Yes	A domain, a URL or a bare name. A bare name (e.g. hvn) is tried with the popular endings at once and answers kind: "expand" with a results list.
`refresh`	No	Set to 1 to skip the cached answer and ask the source again.
`lang`	No	Message language: vi or en.

Example request · curl

curl -s "https://who.com.vn/api/v1/whois?domain=hvn.vn" \
  -H "Authorization: Bearer $WHO_API_KEY"

Example response · application/json

{
  "kind": "single",
  "domain": "hvn.vn",
  "unicode": "hvn.vn",
  "status": "registered",
  "unconfirmed": false,
  "registrant": {
    "type": "organization",
    "name": "Công ty Cổ phần Tập đoàn HVN"
  },
  "registrar": "Công ty TNHH P.A Việt Nam",
  "created_at": "2016-04-18",
  "expires_at": "2030-04-18",
  "updated_at": null,
  "registrar_expires_at": null,
  "nameservers": [
    "art.ns.cloudflare.com",
    "lily.ns.cloudflare.com"
  ],
  "epp_status": [
    "clientTransferProhibited"
  ],
  "dnssec": null,
  "raw": "hvn.vn : Record found !\nDomain : hvn.vn\nStatus : clientTransferProhibited\nIssue Date : 2016-04-18T00:00:00+07:00\nExpired Date : 2030-04-18T00:00:00+07:00\nRegistrar Name : Công ty TNHH P.A Việt Nam\nOwner Name : Công ty Cổ phần Tập đoàn HVN\nDNS : art.ns.cloudflare.com, lily.ns.cloudflare.com",
  "source": "netvn",
  "source_label": "whois.net.vn",
  "fetched_at": "2026-10-05T02:15:08.412Z",
  "cached": false,
  "stale": false,
  "days_left": 1291,
  "age_days": 3822
}

days_left and age_days are counted from today in Vietnam. status is registered, available, unknown or unsupported; unknown means no source answered with certainty — retry later, never treat it as available.

Domain lifecycle

GET/api/v1/lifecycle· Key scope: lifecycle

The whois answer plus the milestones after the expiry date (suspension, last day to renew, redemption, release) under the rules of the domain's ending.

Query parameters

Parameter	Required	Description
`domain`	Yes	A full domain name, e.g. hvn.vn.
`lang`	No	Language of the milestone labels: vi or en.

Example request · curl

curl -s "https://who.com.vn/api/v1/lifecycle?domain=hvn.vn" \
  -H "Authorization: Bearer $WHO_API_KEY"

Example response · application/json

{
  "whois": {
    "kind": "single",
    "domain": "hvn.vn",
    "unicode": "hvn.vn",
    "status": "registered",
    "unconfirmed": false,
    "registrant": {
      "type": "organization",
      "name": "Công ty Cổ phần Tập đoàn HVN"
    },
    "registrar": "Công ty TNHH P.A Việt Nam",
    "created_at": "2016-04-18",
    "expires_at": "2030-04-18",
    "updated_at": null,
    "registrar_expires_at": null,
    "nameservers": [
      "art.ns.cloudflare.com",
      "lily.ns.cloudflare.com"
    ],
    "epp_status": [
      "clientTransferProhibited"
    ],
    "dnssec": null,
    "raw": "hvn.vn : Record found !\nDomain : hvn.vn\nStatus : clientTransferProhibited\nIssue Date : 2016-04-18T00:00:00+07:00\nExpired Date : 2030-04-18T00:00:00+07:00\nRegistrar Name : Công ty TNHH P.A Việt Nam\nOwner Name : Công ty Cổ phần Tập đoàn HVN\nDNS : art.ns.cloudflare.com, lily.ns.cloudflare.com",
    "source": "netvn",
    "source_label": "whois.net.vn",
    "fetched_at": "2026-10-05T02:15:08.412Z",
    "cached": false,
    "stale": false,
    "days_left": 1291,
    "age_days": 3822
  },
  "lifecycle": {
    "state": "registered",
    "groupId": "vn",
    "anchorDate": "2030-04-18",
    "anchorSource": "registry",
    "ageYears": 10,
    "daysLeft": 1291,
    "currentIndex": -1,
    "currentFromStatus": null,
    "milestones": [
      {
        "key": "suspended",
        "label": "Suspended",
        "desc": "Website and email stop working; renewal is still possible.",
        "period": "Just expired",
        "date": "2030-04-19",
        "daysFromToday": 1292,
        "isProjected": true,
        "isCurrent": false
      },
      {
        "key": "renew_deadline",
        "label": "Last day to renew",
        "desc": "After this date the domain can no longer be renewed.",
        "period": "Suspended · awaiting renewal",
        "date": "2030-05-18",
        "daysFromToday": 1321,
        "isProjected": true,
        "isCurrent": false
      },
      {
        "key": "released",
        "label": "Released",
        "desc": "The domain is withdrawn and can be registered again.",
        "period": "Pending release",
        "date": "2030-05-24",
        "daysFromToday": 1327,
        "isProjected": true,
        "isCurrent": false
      }
    ],
    "note": "The lifecycle is indicative; dates after today are projected."
  }
}

Milestones after today are projections (isProjected: true).

DNS records

GET/api/v1/dns· Key scope: dns

DNS records asked of the domain's authoritative name server, compared with a public resolver, with quick hints (email and DNS providers, SPF).

Query parameters

Parameter	Required	Description
`domain`	Yes	A domain or subdomain; an IP address looks up its PTR record.
`types`	No	Comma-separated record types: A, AAAA, CNAME, MX, NS, TXT, SOA, CAA, SRV. Leave empty for all.
`lang`	No	Error message language: vi or en.

Example request · curl

curl -s "https://who.com.vn/api/v1/dns?domain=hvn.vn&types=A,MX,NS" \
  -H "Authorization: Bearer $WHO_API_KEY"

Example response · application/json

{
  "host": "hvn.vn",
  "records": [
    {
      "host": "hvn.vn",
      "type": "A",
      "value": "103.124.95.203",
      "ttl": 300
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx.l.google.com",
      "ttl": 300,
      "priority": 10
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "alt1.aspmx.l.google.com",
      "ttl": 300,
      "priority": 20
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "alt2.aspmx.l.google.com",
      "ttl": 300,
      "priority": 20
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx2.googlemail.com",
      "ttl": 300,
      "priority": 30
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx3.googlemail.com",
      "ttl": 300,
      "priority": 30
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx4.googlemail.com",
      "ttl": 300,
      "priority": 30
    },
    {
      "host": "hvn.vn",
      "type": "MX",
      "value": "aspmx5.googlemail.com",
      "ttl": 300,
      "priority": 30
    },
    {
      "host": "hvn.vn",
      "type": "NS",
      "value": "art.ns.cloudflare.com",
      "ttl": 86400
    },
    {
      "host": "hvn.vn",
      "type": "NS",
      "value": "lily.ns.cloudflare.com",
      "ttl": 86400
    }
  ],
  "source": "authoritative",
  "authoritativeServer": "art.ns.cloudflare.com",
  "authoritativeUnavailable": false,
  "diffs": [],
  "hints": {
    "mailProviders": [
      "Google Workspace"
    ],
    "dnsProviders": [
      "Cloudflare"
    ],
    "spf": null,
    "dmarc": null
  },
  "fetched_at": "2026-10-05T02:15:08.412Z",
  "cached": false
}

error.code, when present, is nxdomain, dns_failed or private_ip; when the authoritative server does not answer, source is public.

Bulk lookup

POST/api/v1/whois/bulk· Key scope: bulk

Send a list of domains and receive one line per domain as soon as each lookup finishes.

Query parameters

Parameter	Required	Description
`lang`	No	Error message language: vi or en.

JSON request body

Field	Required	Description
`domains`	Yes	Array of domain names. Duplicates are merged, invalid entries are reported in the meta line, and the list is cut at the per-run maximum.

Example request · curl

curl -s -X POST "https://who.com.vn/api/v1/whois/bulk" \
  -H "Authorization: Bearer $WHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["hvn.vn","hvn.com.vn","hvn"]}'

Example response · application/x-ndjson

{"type":"meta","total":2,"truncated":false,"domains":["hvn.vn","hvn.com.vn"],"invalid":[{"input":"hvn","code":"no_tld"}],"invalidCount":1}
{"type":"row","index":1,"input":"hvn.com.vn","result":{"kind":"single","domain":"hvn.com.vn","unicode":"hvn.com.vn","status":"registered","unconfirmed":false,"registrant":{"type":"organization","name":"Công ty Cổ phần Tập đoàn HVN"},"registrar":"Công ty TNHH P.A Việt Nam","created_at":"2019-04-26","expires_at":"2027-04-26","updated_at":null,"registrar_expires_at":null,"nameservers":["ns1.hkda.vn","ns2.hkda.vn","ns3.hkda.vn"],"epp_status":["clientTransferProhibited"],"dnssec":null,"raw":"hvn.com.vn : Record found !\nDomain : hvn.com.vn\nStatus : clientTransferProhibited\nIssue Date : 2019-04-26T00:00:00+07:00\nExpired Date : 2027-04-26T00:00:00+07:00\nRegistrar Name : Công ty TNHH P.A Việt Nam\nOwner Name : Công ty Cổ phần Tập đoàn HVN\nDNS : ns1.hkda.vn, ns2.hkda.vn, ns3.hkda.vn","source":"netvn","source_label":"whois.net.vn","fetched_at":"2026-10-05T02:15:08.412Z","cached":false,"stale":false,"days_left":203,"age_days":2719}}
{"type":"row","index":0,"input":"hvn.vn","result":{"kind":"single","domain":"hvn.vn","unicode":"hvn.vn","status":"registered","unconfirmed":false,"registrant":{"type":"organization","name":"Công ty Cổ phần Tập đoàn HVN"},"registrar":"Công ty TNHH P.A Việt Nam","created_at":"2016-04-18","expires_at":"2030-04-18","updated_at":null,"registrar_expires_at":null,"nameservers":["art.ns.cloudflare.com","lily.ns.cloudflare.com"],"epp_status":["clientTransferProhibited"],"dnssec":null,"raw":"hvn.vn : Record found !\nDomain : hvn.vn\nStatus : clientTransferProhibited\nIssue Date : 2016-04-18T00:00:00+07:00\nExpired Date : 2030-04-18T00:00:00+07:00\nRegistrar Name : Công ty TNHH P.A Việt Nam\nOwner Name : Công ty Cổ phần Tập đoàn HVN\nDNS : art.ns.cloudflare.com, lily.ns.cloudflare.com","source":"netvn","source_label":"whois.net.vn","fetched_at":"2026-10-05T02:15:08.412Z","cached":false,"stale":false,"days_left":1291,"age_days":3822}}
{"type":"done"}

The answer has Content-Type application/x-ndjson: one JSON object per line.
The first line, type: "meta", lists the domains that will be checked (domains, in index order) and the invalid entries. Then one type: "row" line per domain, in the order they finish — match them by index; a row carries either result (as in whois) or error. The last line is type: "done".
Closing the connection stops the remaining lookups.

Export to Excel / CSV

POST/api/v1/whois/export· Key scope: export

Export the cached whois answers of a list of domains to an Excel or CSV file (Vietnamese text displays correctly). Never triggers new lookups.

Query parameters

Parameter	Required	Description
`lang`	No	Column header language: vi or en.

JSON request body

Field	Required	Description
`domains`	Yes	Array of domain names, usually the list you just bulk-looked up.
`format`	Yes	xlsx or csv.

Example request · curl

curl -s -X POST "https://who.com.vn/api/v1/whois/export" \
  -H "Authorization: Bearer $WHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["hvn.vn","hvn.com.vn"],"format":"xlsx"}' \
  -o who-com-vn.xlsx

Domains not looked up recently get an empty row — run a bulk lookup first.

Error codes

Errors come with the matching HTTP status and a JSON body: error (machine-readable code), message (in the requested language) and retryAfter (seconds, when relevant). The message column below is what the API returns.

Code	HTTP	Message
`key_in_query`	400	Do not put the API key in the URL; send it in the Authorization: Bearer <key> header.
`invalid_api_key`	401	The API key is invalid, revoked or expired.
`scope_denied`	403	This API key is not allowed to use this endpoint.
`rate_limited`	429	You are looking up too fast — please try again in 60 seconds.
`quota_exceeded`	429	This API key has used its monthly quota. Contact HVN to raise it.
`bad_request`	400	Invalid request.
`payload_too_large`	413	The request is too large.
`emptyinvalid_charslabel_too_longtoo_longunsupported_tldsuffix_onlyno_tldmultiple_domainsis_ipprivate_ip`	400	The domain given is not valid; message explains exactly why.
`internal`	500	Something went wrong — please try again later.

Example error

HTTP/2 401
www-authenticate: Bearer realm="who.com.vn"
content-type: application/json

{
  "error": "invalid_api_key",
  "message": "The API key is invalid, revoked or expired."
}

Limits

Limits keep the shared data sources stable. Going over a limit returns 429 with a Retry-After header.

Without a key (per IP address, currently in force)

30 lookups per minute (whois, lifecycle, DNS). A bare name tries 6 popular endings, so it counts as 6 lookups.
Bulk lookup: 5 runs per hour, up to 25 domains each.
Export: 20 files per hour.

With an API key

Lookups per minute, lookups per month, bulk runs per hour and domains per run are set for each key as agreed with HVN.
The monthly quota counts domains looked up (a bulk run counts its domains; an export counts 1) and resets on the 1st of each month, Vietnam time. When it runs out the API answers 429 quota_exceeded.
Export: 20 files per hour per key.

Limit headers

When a keyed request is counted, the answer carries these headers (also on a 429 rate_limited answer):

Header	Description
`X-RateLimit-Limit`	Maximum calls in the current window (per minute; per hour for bulk lookup and export).
`X-RateLimit-Remaining`	Calls left in the current window.
`X-RateLimit-Reset`	Seconds until the current window ends.
`X-Quota-Limit`	The key's monthly quota.
`X-Quota-Remaining`	Monthly quota left.
`Retry-After`	With 429: seconds to wait before retrying (quota_exceeded: until the next month starts, Vietnam time).
`WWW-Authenticate`	With 401: Bearer realm="who.com.vn".

Personal data

The API follows the same personal data policy as the website (Decree 13/2023/ND-CP): for domains held by individuals the name and contact details are hidden by default — registrant.type is individual, registrant.name is null and personal details are removed from the raw record. Organisation names are shown.

Each keyed request is logged against its key (domains of individual registrants are not logged) for usage statistics.

Read the Data policy

Request API access

Send the details below and the HVN team will contact you to agree on limits and issue a key. The API is currently free of charge.

Contact

For integration advice or higher limits, contact HVN GROUP:

Hotline024.9999.7777 Emailkinhdoanh@hvn.vn