VietnamWorks public jobs Actor

This Actor searches VietnamWorks public job listings or enriches one or more public job pages. It writes one dataset row for each job whose detail page matches the requested job ID and title. The three identity fields are always present; other business facts are included when VietnamWorks publishes them.

Choose a mode

search is the default. It sends query to VietnamWorks public search, inspects up to maxPages, and enriches up to maxItems matching jobs. single looks up the one URL in jobUrls. multiple looks up between 1 and 20 URLs in jobUrls. Direct modes accept the default query developer; they do not run a keyword search.

Job URLs must be native HTTPS VietnamWorks pages in the form https://www.vietnamworks.com/<slug>-<id>-jd or ...-jv. Safe Vietnamese Unicode in the slug is accepted. Each URL is limited to 2048 characters and cannot include a query string or fragment.

Input fields

Every top-level input field is optional because it has a default or is conditional on the selected mode. Unknown fields and aliases such as jobUrl or startUrls are rejected.

Field	Type	Required?	Default	Bounds
mode	string	No	search	search, single, or multiple
query	string	No	developer	1–100 characters; can change only in search mode
jobUrls	string array	Mode-dependent	[]	Empty in search; exactly 1 in single; 1–20 in multiple; each native URL up to 2048 characters
maxPages	integer	No	1	1–5 in search; exactly 1 in direct modes
maxItems	integer	No	3	1–100 in every mode
pageSize	integer	No	10	1–100 in search; exactly 10 in direct modes
maxRequests	integer	No	20	1–200; includes robots checks and redirect hops
requestDelayMs	integer	No	1000	1000–10000 milliseconds
requestTimeoutSecs	integer	No	30	5–30 seconds per request
proxyConfiguration	object	No	{}	Standard SDK fields described below; extra fields are rejected

proxyConfiguration accepts these four standard Apify SDK fields:

Field	Type	Required?	Default	Bounds
useApifyProxy	boolean	No	—	Must be true when apifyProxyGroups or apifyProxyCountry is set
apifyProxyGroups	string array	No	—	Up to 5 unique uppercase group names; a non-empty list requires useApifyProxy: true
apifyProxyCountry	string	No	—	Two uppercase letters; requires useApifyProxy: true
proxyUrls	string array	No	—	Up to 10 valid HTTP(S) URLs, each at most 2048 characters; cannot be combined with any Apify proxy field

For example, Apify Proxy settings can be supplied as "proxyConfiguration": {"useApifyProxy": true, "apifyProxyCountry": "VN"}. Custom proxy URLs can be supplied as "proxyConfiguration": {"proxyUrls": ["http://user:password@proxy.example:8000"]}.

Input examples

The repository includes one canonical example for each mode: ./INPUT.json, ./INPUT-single.json, and ./INPUT-multiple.json.

Dataset fields

The dataset schema is in ./.actor/dataset_schema.json. Each row contains these job and company facts when available:

Field	Meaning
jobId, jobTitle, jobUrl	Required native job identity: source ID, published title, and canonical detail-page URL.
company	Published employer name.
companyProfileUrl, companyLogoUrl	Public company profile and logo URLs.
companyDescription, companyDescriptionHtml	Company profile text and sanitized rich HTML.
contactEmail	Public recruiting contact email, when present.
location, address, country	Display location, published address, and country only when the page explicitly names it.
workingLocations	Structured location names and addresses; see the nested fields below.
description, descriptionHtml	Full published role description as readable text and sanitized rich HTML.
requirements, requirementsHtml	Full published requirements as readable text and sanitized rich HTML.
benefits, skills	Published benefits and skills as arrays of strings.
jobLevel, jobLevelVI	Job level labels in English and Vietnamese when available.
jobFunction, industry, employmentType	Published job function, industry, and employment type labels.
salary, salaryMin, salaryMax	Numeric salary values only when the source provides them.
salaryCurrency, salaryText	Explicit source currency, when published, and the salary wording shown by VietnamWorks.
datePosted, dateApproved, validThrough, lastUpdatedOn, onlineOn	Source posting, approval, expiry, update, and online dates. Date-only values remain date-only; timestamps include their timezone and are normalized to UTC.
postedLabel	Published relative or display label, such as “Posted recently.”
views	Published view count, including zero.
applicationUrl	Public application URL when the detail page provides one.
jobInformation	Additional published requirements and work-schedule facts; see the nested fields below.

Each object in workingLocations may contain these source-provided labels and addresses:

Field	Meaning
name	Combined or display name for the work location.
cityName, cityNameVI	City labels in English and Vietnamese.
stateProvinceName, stateProvinceNameVI	State or province labels in English and Vietnamese.
regionName, regionNameVI	Region labels in English and Vietnamese.
districtName, districtNameVI	District labels in English and Vietnamese.
address	Published street or site address.
countryName, countryNameVI	Country labels in English and Vietnamese, only when the source supplies them.

jobInformation may contain these published job requirements and schedule facts:

Field	Meaning
language, languageVI	Required or selected language labels in English and Vietnamese.
yearsOfExperience	Published experience requirement, retaining a number or string.
highestDegree, highestDegreeVI	Education requirement in English and Vietnamese.
workingDays	Published work days, as a string or list.
workingFromHour, workingToHour	Start and end of the published work schedule.
requiredResume, requiredCoverLetter	Whether the application requires a resume or cover letter, retaining the source value.
numberOfRecruits	Published recruit count, including zero.
employmentType	Published employment type labels.
workArrangement	Published work arrangement, such as office or hybrid, when stated.

HTML fields are sanitized to retain readable formatting while removing scripts, forms, and unsafe attributes or links. Optional values are omitted when absent. The Actor does not infer currency or location facts that the page does not state.

Here is a complete example record. Every value is fictional and is included only to show the output shape:

{
  "jobId": "99999999",
  "jobTitle": "Fictional Senior Backend Engineer",
  "jobUrl": "https://www.vietnamworks.com/fictional-senior-backend-engineer-99999999-jd",
  "company": "Example Software Cooperative",
  "companyProfileUrl": "https://example.invalid/example-software-cooperative",
  "companyLogoUrl": "https://example.invalid/images/example-software-logo.png",
  "companyDescription": "Example Software Cooperative builds reliable tools for fictional organizations.",
  "companyDescriptionHtml": "<p>Example Software Cooperative builds reliable tools for fictional organizations.</p>",
  "contactEmail": "hiring@example.invalid",
  "location": "Đà Nẵng | Thành phố Đà Nẵng | Vietnam | 12 Example Avenue",
  "country": "Vietnam",
  "address": "12 Example Avenue",
  "workingLocations": [
    {
      "name": "Hai Chau, Da Nang",
      "cityName": "Da Nang",
      "cityNameVI": "Đà Nẵng",
      "stateProvinceName": "Da Nang",
      "stateProvinceNameVI": "Thành phố Đà Nẵng",
      "regionName": "Central Vietnam",
      "regionNameVI": "Miền Trung Việt Nam",
      "districtName": "Hai Chau District",
      "districtNameVI": "Quận Hải Châu",
      "address": "12 Example Avenue",
      "countryName": "Vietnam",
      "countryNameVI": "Việt Nam"
    }
  ],
  "description": "Mô tả công việc\nBuild and maintain fictional payment services with a small engineering team.\n\nKey responsibilities\n• Design reliable backend services\n• Review changes and improve monitoring",
  "descriptionHtml": "<h2>Mô tả công việc</h2><p>Build and maintain fictional payment services with a small engineering team.</p><h3>Key responsibilities</h3><ul><li>Design reliable backend services</li><li>Review changes and improve monitoring</li></ul>",
  "requirements": "Yêu cầu\nExperience with Java, REST APIs, databases, and clear written communication.",
  "requirementsHtml": "<h2>Yêu cầu</h2><p>Experience with Java, REST APIs, databases, and clear written communication.</p>",
  "benefits": [
    "Fictional annual learning allowance",
    "Flexible paid leave"
  ],
  "skills": [
    "Java",
    "REST APIs",
    "PostgreSQL"
  ],
  "jobLevel": "Experienced (non-manager)",
  "jobLevelVI": "Nhân viên có kinh nghiệm",
  "jobFunction": "Information Technology > Software Developer",
  "industry": "Software Services",
  "employmentType": [
    "Full-time"
  ],
  "salary": 100000000,
  "salaryMin": 80000000,
  "salaryMax": 120000000,
  "salaryCurrency": "VND",
  "salaryText": "80,000,000–120,000,000 VND per month",
  "datePosted": "2026-08-14T03:30:00.000Z",
  "dateApproved": "2026-08-15T02:00:00.000Z",
  "validThrough": "2026-09-14T16:59:59.000Z",
  "lastUpdatedOn": "2026-08-15T02:00:00.000Z",
  "onlineOn": "2026-08-15T02:15:00.000Z",
  "postedLabel": "Posted recently",
  "views": 0,
  "applicationUrl": "https://example.invalid/apply/fictional-job-99999999",
  "jobInformation": {
    "language": "English",
    "languageVI": "Tiếng Anh",
    "yearsOfExperience": 4,
    "highestDegree": "Bachelor's degree",
    "highestDegreeVI": "Bằng cử nhân",
    "workingDays": "Monday-Friday",
    "workingFromHour": "09:00",
    "workingToHour": "18:00",
    "requiredResume": true,
    "requiredCoverLetter": false,
    "numberOfRecruits": 0,
    "employmentType": [
      "Full-time"
    ],
    "workArrangement": "Hybrid"
  }
}```

## Request handling and run summary

Requests are sequential and bounded by `maxRequests`, `requestDelayMs`, and `requestTimeoutSecs`. The configured SDK proxy is used when supplied. The Actor does not retry requests or switch routes or identities. A robots disallow rule, login wall, challenge, or HTTP 401, 403, 429, or 451 stops further source requests.

The only Actor-written public key-value-store entry is `OUTPUT_SUMMARY`, with exactly `status`, `itemsStored`, and `isPartial`. A record counts only after the dataset confirms its write. A clean empty result is `SUCCEEDED` with zero items and `isPartial: false`. If a failure happens before any row is stored, the run is `FAILED` with `isPartial: false`. If at least one row is stored before a later failure, the run remains `SUCCEEDED` with `isPartial: true`.

## Run locally

Use a new actor-relative storage directory for each run and keep existing storage intact. For example, in PowerShell:

```powershell
$runStore = 'storage-vietnamworks-validation'
if (Test-Path -LiteralPath $runStore) { throw "Run storage already exists: $runStore" }
$env:APIFY_LOCAL_STORAGE_DIR = $runStore
apify run --resurrect --input-file .\INPUT.json

The Actor input schema is in ./.actor/input_schema.json. Run the local pure checks with npm test and npm run check.