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.

4 min readLast updated October 20, 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 employer company. It records the country, the accreditation number and 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.
`jobsiteCountry`, `jobsiteCity`	Where the work actually is. Drives country-specific handling.
`dateApproved`	Optional approval date. Separate from the creation/receipt date; existing orders show “Not recorded” until supplied.
`validUntil`	Optional last valid day. It cannot precede Date approved. New orders remain valid through this UTC day, then disappear from applicant intake and are swept to `EXPIRED` by the nightly job.
`contractDurationMonths`	The length of the employment contract in months.
`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.

See who applied for a job#

Staff: open a job order to see Job applicants at the top of its Overview, or select the Job applicants tab. Employers: open Recruitment and click the job title or View applicants. Employers can only open lists for their own jobs.

The list includes mobile submissions, applications awaiting staff review, and closed applications. Each entry shows the applicant name and number, position, application date, current stage and status. Search by name or applicant number, filter by position, and use the page controls to browse every application.

Select View to open the applicant profile as staff, or the authorized application details as an employer. Returning keeps your job, search, position filter and page selected. On small screens, the list uses cards so the stage and View button remain visible.

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?