Skip to main content

Create recruitment check

POST 
/openapi/v1/recruitment-checks

Send a new credential check to an applicant.

Applicant identification — exactly one of:

  • applicant.id (synthetic id like app_…)
  • applicant.externalId + optional sourceSystem (HRIS/ATS id)
  • applicant.details (firstName + lastName + email, optional externalId) — find-or-create by email; externalId is stamped onto the applicant only when a new one is created

Requirements — exactly one of:

  • screeningPackageCode — snapshots requirements + per-credential guiding texts + banChecks from a stored, active package. Returns 422 if the package is missing or inactive.
  • requirements — ad-hoc, one of two shapes:
    • requirements.credentialTypes (flat AND shortcut, with optional peer requirements.exemptions)
    • requirements.group (full AND/OR tree mirroring OhoScreeningPackageConditionGroup; supports nested groups, exemptions, per-group guiding text, attachmentRequired, skippable; max nesting depth 5)

Ad-hoc checks are stamped with screeningPackageCode = "adhoc". requirements.banChecks (e.g. ["AGED_CARE_QUALITY"]) is snapshotted to the check so submission fires the right registry checks.

Exemption codes are bare credential codes (e.g. "WWCC_QLD") — the renderer adds the EX: display prefix. Prefixed codes on the wire are rejected with 400.

See docs/dev-guides/recruitment-check-api-testing.md for end-to-end example payloads.

Request​

Responses​

OK