Masothue APImasothue.com ↗
Search and retrieve Vietnamese company tax registration data via the masothue.com API. Get tax codes, addresses, representatives, and business status.
What is the Masothue API?
The masothue.com API provides 2 endpoints for querying Vietnam's company tax registration database. Use search_company to find businesses by name, tax code, national ID, or representative name, and get_company_detail to retrieve 10 structured fields per company including operating status, active date, managing tax office, primary industry, and legal entity type.
curl -X GET 'https://api.parse.bot/scraper/7c178373-f050-44cc-a501-77854e1f2f14/search_company?page=1&type=auto&query=Vinamilk' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace masothue-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: MaSoThue Vietnam Tax Code Lookup — bounded, re-runnable."""
from parse_apis.masothue_vietnam_tax_code_lookup_api import MaSoThue, SearchType, CompanyNotFound
client = MaSoThue()
# Search for companies by name — limit= caps TOTAL items fetched across all pages.
for company in client.companysummaries.search(query="Vinamilk", type=SearchType.AUTO, limit=5):
print(company.name, company.tax_code, company.address)
# Drill-down: take the first result, then fetch full details via sub-resource nav.
summary = client.companysummaries.search(query="FPT", limit=1).first()
if summary:
detail = summary.details()
print(detail.company_name, detail.status, detail.representative, detail.main_industry)
# Direct lookup by tax code using the companies collection.
try:
company = client.companies.get(tax_code="0314539064")
print(company.company_name, company.tax_code, company.active_date, company.managed_by)
except CompanyNotFound as exc:
print(f"Company not found: {exc.tax_code}")
print("exercised: companysummaries.search / summary.details / companies.get")
Full-text search over Vietnamese companies by name, tax code, ID number, or representative name. Returns up to 20 companies per page. Pagination via integer page counter. The search type narrows the interpretation of the query string — 'auto' lets the server decide.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| type | string | Search type filter. |
| queryrequired | string | Search query - company name, tax code, ID number, or representative name. |
{
"type": "object",
"fields": {
"page": "integer - current page number",
"type": "string - the search type used",
"query": "string - the search query submitted",
"companies": "array of company objects with name, tax_code, representative, address, detail_path",
"total_pages": "integer - total number of pages available",
"result_count": "integer - number of companies returned on this page"
},
"sample": {
"data": {
"page": 1,
"type": "auto",
"query": "Vinamilk",
"companies": [
{
"name": "CÔNG TY TNHH VINAMILK TÂN SƠN",
"address": "Số 357 Vườn Lài, Phường Phú Thọ Hoà, Quận Tân Phú, Thành phố Hồ Chí Minh, Việt Nam",
"tax_code": "0314539064",
"detail_path": "/0314539064-cong-ty-tnhh-vinamilk-tan-son",
"representative": "KIỀU LỆ QUYÊN"
}
],
"total_pages": 5,
"result_count": 20
},
"status": "success"
}
}About the Masothue API
Search Vietnamese Companies
The search_company endpoint accepts a required query string and an optional type parameter to narrow how the query is interpreted. Accepted type values include auto, enterpriseTax, personalTax, identity, enterpriseName, and legalName. Results are paginated at up to 20 companies per page, with total_pages and result_count returned alongside each page. Each item in the companies array includes the company's name, tax code, representative, address, and a detail_path string used to fetch the full profile.
Company Detail Lookup
The get_company_detail endpoint accepts either a tax_code or a detail_path from prior search results. The detail_path approach is the most reliable way to resolve a specific entity — for example, passing /0314539064-cong-ty-tnhh-vinamilk-tan-son navigates directly to that company's record. The response covers company_name, short_name, company_type, status, active_date, address, tax_address, managed_by, and main_industry.
Data Coverage and Scope
All data reflects registered Vietnamese enterprises as recorded in the public tax registration system. Fields are returned in Vietnamese where the source record uses Vietnamese text. The tax_code field preserves leading zeros, which is important for correct identification of entities with codes beginning in 0. The active_date field follows YYYY-MM-DD format.
The Masothue API is a managed, monitored endpoint for masothue.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when masothue.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official masothue.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Verify a Vietnamese supplier's tax registration status and active date before onboarding
- Resolve a company's official registered address and tax address from its tax code
- Identify the legal representative associated with a specific enterprise tax number
- Classify Vietnamese counterparties by company_type and main_industry for CRM enrichment
- Cross-reference an identity number against registered businesses to detect sole proprietors
- Build a due-diligence workflow that flags companies with non-active status
- Look up which tax office manages a given company via the managed_by field
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.