# Vietnam Business Tax Status Lookup (`longnguyen054/vietnam-business-tax-status-lookup`) Actor Look up the registered name and raw operating status of Vietnamese businesses by tax code (MST). - **URL**: https://apify.com/longnguyen054/vietnam-business-tax-status-lookup.md - **Developed by:** [Nguyen Long](https://apify.com/longnguyen054) (community) - **Categories:** Automation, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $10.00 / 1,000 successful tax code results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Vietnam Business Tax Status Lookup Look up the registered company name and the original operating-status text published by Vietnam's public tax portal for one or more business tax codes (MST — mã số thuế), and get the results as structured JSON, CSV, Excel, API or MCP output. > **Unofficial Actor. Not affiliated with or endorsed by Vietnam's tax authority.** ### Features What it does: - Looks up 1–50 Vietnamese business tax codes per run, sequentially and politely. - Returns exactly the source data the tax portal publishes: the tax code, the registered company name, and the raw status text (`statusRaw`). - Deduplicates input, validates tax-code format before any network call, and solves the portal's CAPTCHA internally — you never need a portal account or credentials. - Charges only for successful results (see Pricing). What it does not do: - It does not classify, translate or interpret the status. `statusRaw` is the portal's own wording (Vietnamese), only HTML-decoded and whitespace-trimmed. - It does not search by company name or address, and does not return full registration records. - It does not add derived fields such as `isOperating` — no legal conclusions, no risk scores. ### How to use 1. Click **Start**. The prefilled example tax code runs with zero configuration. 2. Replace the example with your own tax codes (one per line, up to 50). 3. Click **Start** again and wait for the run to finish. 4. Open the **Dataset** tab to view results, or export them as JSON, CSV or Excel. ### Input The only input field is `taxCodes`: ```json { "taxCodes": ["0101234567", "0101234567-001"] } ```` - 1–50 tax codes per run. - Each code must be 10 digits, optionally followed by `-` and a 3-digit branch suffix. - Duplicates are removed before lookup (each unique code is looked up and charged at most once per run). - Invalid input fails the run before any lookup and nothing is charged. Proxy, timeouts, retries and concurrency are internal, benchmarked product settings — they are intentionally not configurable. ### Output Each successful lookup produces exactly one dataset item with three fields: ```json { "taxCode": "0110181599", "companyName": "CÔNG TY TNHH AIEC", "statusRaw": "NNT đang hoạt động" } ``` The dataset contains successful results only. Tax codes the portal does not find, and lookups that fail technically, produce no items. Diagnostics appear in the run log and status message, never in the dataset. ### Pricing This Actor uses Apify's **pay-per-event** model with a single event: one `tax-code-result` event is charged for each successful result — **pay per successful result**. Platform usage (compute, proxy) is included in the event price. You are **not** charged for: - invalid or duplicate input, - tax codes the portal reports as not found, - CAPTCHA failures, portal outages, blocks, timeouts or any technical error, - tax codes skipped because the run stopped early (circuit breaker, budget or spending limit). A run that stops early keeps (and has charged) the successful items pushed so far. The terminal status message reports how many codes were pushed and charged, how many were not found or failed, and how many were not processed. **When retrying a partial run, submit only the tax codes missing from the dataset** — resubmitting the whole batch is a new lookup and successful codes will be charged again. Deduplication applies within a single run only. ### API and integrations - **Apify Console** — run manually or on a schedule. - **Synchronous API** (`run-sync-get-dataset-items`) — recommended for **1–5 tax codes** only; the endpoint has a 300-second HTTP timeout (the run itself continues if the connection times out). - **Asynchronous API** — recommended for **6–50 tax codes**: start a run, then poll or use a webhook and fetch the dataset. Python: ```python from apify_client import ApifyClient client = ApifyClient("") run = client.actor("").call(run_input={"taxCodes": ["0101234567"]}) items = client.dataset(run["defaultDatasetId"]).list_items().items ``` JavaScript: ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: '' }); const run = await client.actor('').call({ taxCodes: ['0101234567'] }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); ``` curl (async start): ```bash curl -X POST "https://api.apify.com/v2/acts//runs?token=" \ -H "Content-Type: application/json" \ -d '{"taxCodes": ["0101234567"]}' ``` Make, Zapier and n8n can call the Actor through the Apify integration/app; AI agents can call it through Apify's MCP server — the output schema points them at the dataset items automatically. ### FAQ and limitations - **A code returned no item.** The portal reported it as *not found*, or the lookup failed technically. Check the run log; you were not charged for it. - **What if the portal is down?** The Actor checks portal health before looking anything up and fails fast instead of burning retries. Runs stopped this way charge nothing new. - **Why is there no proxy option?** The network route is a benchmarked internal policy included in the price; exposing it would make costs and reliability unpredictable. - **How fast is it?** Typically well under a minute per tax code; large batches run sequentially, so a full 50-code batch can take tens of minutes. Runs have a 60-minute wall-clock limit — if reached, the run ends as partial (`wall_clock_limit_reached`) and keeps the results so far. - **Batch limit** is 50 codes per run. Split larger lists across runs. - **A partial/failed run still shows charged items.** That is by design — every charged item is a delivered result. Retry only the missing codes (see Pricing). ### Data source, privacy, and legal notice Results come from Vietnam's public tax-status lookup portal at the time of the query. Data is a point-in-time reference, not legal advice or an official certificate. The Actor stores only the three output fields in your dataset; it does not store raw HTML or CAPTCHA images, and it never asks for your credentials. **Unofficial Actor. Not affiliated with or endorsed by Vietnam's tax authority.** ### Support and changelog Report problems through the Actor's **Issues** tab in Apify Console. See `CHANGELOG.md` for version history. # Actor input Schema ## `taxCodes` (type: `array`): List of Vietnamese business tax codes (MST) to look up. Each entry must be a 10-digit tax code, optionally followed by a dash and a 3-digit branch suffix (e.g. 0101234567 or 0101234567-001). Maximum 50 codes per run. ## Actor input object example ```json { "taxCodes": [ "0110181599" ] } ``` # Actor output Schema ## `results` (type: `string`): Dataset items for successful lookups only. Each item contains taxCode, companyName and statusRaw exactly as published by the tax portal. Failed or not-found lookups do not produce items. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "taxCodes": [ "0110181599" ] }; // Run the Actor and wait for it to finish const run = await client.actor("longnguyen054/vietnam-business-tax-status-lookup").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "taxCodes": ["0110181599"] } # Run the Actor and wait for it to finish run = client.actor("longnguyen054/vietnam-business-tax-status-lookup").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "taxCodes": [ "0110181599" ] }' | apify call longnguyen054/vietnam-business-tax-status-lookup --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=longnguyen054/vietnam-business-tax-status-lookup", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Vietnam Business Tax Status Lookup", "description": "Look up the registered name and raw operating status of Vietnamese businesses by tax code (MST).", "version": "0.1", "x-build-id": "xvk2Fd8pDMOopp97i" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/longnguyen054~vietnam-business-tax-status-lookup/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-longnguyen054-vietnam-business-tax-status-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/longnguyen054~vietnam-business-tax-status-lookup/runs": { "post": { "operationId": "runs-sync-longnguyen054-vietnam-business-tax-status-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/longnguyen054~vietnam-business-tax-status-lookup/run-sync": { "post": { "operationId": "run-sync-longnguyen054-vietnam-business-tax-status-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "taxCodes" ], "properties": { "taxCodes": { "title": "Tax codes", "minItems": 1, "maxItems": 50, "type": "array", "description": "List of Vietnamese business tax codes (MST) to look up. Each entry must be a 10-digit tax code, optionally followed by a dash and a 3-digit branch suffix (e.g. 0101234567 or 0101234567-001). Maximum 50 codes per run.", "items": { "type": "string", "pattern": "^\\d{10}(?:-\\d{3})?$" } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```