DocsRecruitment

Job orders and positions

How demand from a principal is recorded: job order fields, positions and quotas, validity and expiry, and which matching fields must never be published.

3 min readLast updated September 9, 2026

A job order is demand for one position. It belongs to a principal and is the thing an applicant is endorsed *to*. Create a separate job order when the same employer requests a different position.

Principals come first#

A Principal is the overseas employer company. It records the country, the accreditation number and — importantly — accreditationExpiresAt. An isActive flag takes a principal out of circulation without deleting its history.

People at the principal are PrincipalContact records: name, position, email, phone, one flagged isPrimary, and a hasPortalAccess flag that governs whether they can sign in on the employer surface.

Accreditation expiry is stored but not gated. Nothing currently stops you from endorsing applicants against a principal whose accreditation has lapsed. The date is recorded for your own review. If that matters to your compliance process, watch it deliberately.

The job order record#

Field	Notes
`code`	Your internal reference, formatted like `JO-2026-0001`.
`title`	The job order title as the principal describes it.
`dmwJobOrderNo`	The DMW-issued job order number, kept separate from your internal code so both are traceable.
`jobsiteCountry`, `jobsiteCity`	Where the work actually is. Drives country-specific handling.
`validUntil`	After this date the job order is swept to `EXPIRED` by a nightly job.
`contractDurationMonths`	Typically 24 for land-based deployment.
`salaryAmount`, `salaryCurrency`	Currency defaults to `USD`.
`benefits`	Structured JSON — accommodation, transport, food allowance, annual leave, ticket.
`status`	`DRAFT`, `ACTIVE`, `FILLED`, `CANCELLED` or `EXPIRED`.
`isPublished`	Whether the order appears on your public job board.

Positions and quotas#

Each job order contains exactly one position and its quota. Ten housekeeping attendants belong to one job order; two supervisors require a separate job order. An application always points at that position because its quota is what the team is filling.

A position carries title, quota, and requiredSkills as structured JSON used for matching against an applicant’s skills.

Internal matching fields are not for publication#

Never publish `ageMin`, `ageMax` or `sexPreference`. A position may record an age range and a sex preference because principals state them and you need them for internal shortlisting. They exist for matching only. Publishing them to a job board or an advertisement turns a principal’s requirement into your discriminatory job advertisement. The schema says so explicitly; treat it as a hard rule, not a style preference.

The published job board renders the title, jobsite, salary, contract duration and benefits. The matching fields stay behind the staff surface.

Status and expiry#

Status	When
`DRAFT`	Being prepared. Not published, not endorsable in practice.
`ACTIVE`	Live and accepting endorsements.
`FILLED`	Every position quota met.
`CANCELLED`	The principal withdrew it.
`EXPIRED`	Set automatically once `validUntil` has passed. The sweep runs nightly at 01:15 Asia/Manila.

Expiry matters because a job order that has lapsed while applicants are mid-process is a real operational problem — the visa work continues against demand that no longer formally exists. The nightly sweep makes that visible rather than silent. See Notifications and scheduled jobs.

What the app does today#

One position per job order. The Job orders screen creates one position and quota per order. Opening an order shows its documents, assigned team, vacancy count and applicant pipeline. Select an applicant in the pipeline to see the requirements for their next stage.

Applications, by contrast, are created through the API — that is how an applicant is attached to a position. See Endorsements and the principal portal.

Was this page helpful?