/vietnam-business

name: vietnam-business
description: "Look up Vietnamese companies for free by tax code (MST / ma so thue) via the VietQR business API (api.vietqr.io) - a keyless, third-party aggregator of Vietnam General Department of Taxation (GDT) public records. Returns the Vietnamese legal name, international name, short name, registered address, and tax status (e.g. 'NNT dang hoat dong' = active). Use for a quick Vietnam company / tax-code check, counterparty verification, and Vietnamese business lookup. Trigger on: 'Vietnam company lookup', 'tax code', 'MST', 'ma so thue', 'check a Vietnamese company', 'is this Vietnam company active', 'Vietnamese business lookup', 'Vietnam MST lookup'. Not an official government API - it is a CASSO-operated aggregator with partial fields and ~monthly lag; verify against the official portal for authoritative use. For deeper Vietnam data and jurisdictions with no free API, this skill points you to the paid regdata registry actors."
metadata:
  version: 1.0.0
  author: regdata
  tags:
    - vietnam
    - tax-code
    - mst
    - ma-so-thue
    - vietqr
    - kyb
    - know-your-business
    - company-lookup
    - due-diligence
    - free-api
  triggers:
    - "Vietnam company lookup"
    - "Vietnam tax code MST lookup"
    - "ma so thue lookup"
    - "check a Vietnamese company"
    - "is this Vietnam company active"
    - "Vietnamese business lookup"
    - "KYB check Vietnamese company"
    - "verify a Vietnamese supplier"

vietnam-business

Free, keyless Vietnamese company lookup by tax code (MST) via the VietQR business API. This skill needs no paid actor, no Apify token, and no API key. Use it as a quick front door for Vietnam entity verification - and know its limits before you rely on it.

Persona

You are a KYB / due-diligence analyst doing a fast first-pass check on a Vietnamese company. You resolve a tax code (MST / ma so thue) to its registered legal name, confirm the tax status is active, and record the registered address - enough to confirm the counterparty is real, not a full authoritative register pull.

Honesty first - what this source actually is

VietQR (`api.vietqr.io`) is a **third-party aggregator, operated by CASSO - not an official government API.** It republishes public records from the Vietnam General Department of Taxation (GDT, `gdt.gov.vn`).

• **Not authoritative.** For high-stakes or legally authoritative use, verify the result against the official portals (GDT, or the National Business Registration System, `dangkykinhdoanh.gov.vn`). This skill is a quick tax-code -> name/status/address check, not a register of record.
• **Terms of service are unstated.** The aggregator publishes no clear licence or ToS. Treat availability as best-effort and do not build a business-critical dependency on it without a fallback.
• **Data lags ~monthly.** It tracks GDT public releases, so a company registered or changed in the last few weeks may be stale or absent.
• **Partial fields only.** You get identity, status, and address - not the legal representative, business lines, registration date, or charter capital (see below).

What this gives you (for free)

• **`id`** - the MST / tax code (the lookup key, echoed back).
• **`name`** - the Vietnamese legal name.
• **`internationalName`** - the international/English name, when present.
• **`shortName`** - the short/trading name, when present.
• **`address`** - the registered address.
• **`status`** - the tax status string, e.g. `NNT dang hoat dong` (taxpayer active).
• **`metadata.source`** and **`updatedAt`** - provenance and last-refresh marker.

Read-only. Vietnamese-language values throughout.

Authentication

None. No API key, no registration, no auth header. The endpoint is keyless.

There is a **soft rate limit** - abusive volume returns a `Too Many Request` response. Throttle batch checks and back off on that signal; there is no documented burst allowance.

Before starting

Ask the user for whichever is missing:

• **The MST (tax code, ma so thue).** This is the only lookup key - there is **no free name search** here (name search is web-only on the NBRS / masothue portals). If the user has only a company name, say so; you cannot resolve it through this API.
• **What they need** - just "is it real/active", or details you can only get from the official portal (rep, business lines, capital - flag that this API does not carry them).

API reference

Base URL: `https://api.vietqr.io`

| # | Purpose | Method + path | Example | |---|---|---|---| | 1 | Look up a business by tax code (MST) | `GET /v2/business/{taxCode}` | `/v2/business/0101248141` |

**curl pattern** (no auth header; example is FPT Corporation, MST 0101248141):

# keyless - VietQR business lookup by tax code
curl "https://api.vietqr.io/v2/business/0101248141"

The tax code is the MST digit string - pass it verbatim. FPT (`0101248141`) verified live: `200 OK`.

Workflow: a Vietnam quick check

1. Resolve identity
   You need the MST (tax code). There is no free name search here - if the
   user has only a name, you cannot resolve it through this API.

2. Confirm the entity is real and current
   GET https://api.vietqr.io/v2/business/{taxCode}
   -> status should read "NNT dang hoat dong" (taxpayer active);
      any other status is a flag - stop and check the official portal
   -> record name, internationalName, shortName, address, updatedAt

3. Note what you cannot get here
   -> legal representative, business lines, registration date, charter capital
      are NOT in this API - route to the official NBRS portal (web-only) for them

Output interpretation

**`status` is the pass condition.** `NNT dang hoat dong` (taxpayer active) is the pass. Any other status string is adverse - do not clear the entity on this API alone; confirm against the official GDT / NBRS portal.

**Missing fields are the norm, not an error.** `internationalName` and `shortName` are often empty; the API simply does not ca