Skip to content

Onboarding

Audience: domain, product, backend, ux
Status: specced
Owns: product + backend
Depends on: Auth module, Identity, Personas

OpenAPI covers start / mine / get / save / submit for all personas. An account may hold candidate and centre-staff onboardings (whitelist). Assessor and awarding-body mixes remain 409.

Staff onboarding is person-scoped (persona: centre, variant: staff): completing it once unlocks every current and future CentreStaff membership. It is not per centre and is not org founding (variant: organisation / CentreOnboardingPayload).

Organisation founding: on successful org submit, CAP provisions a Centre (pending) and founder CentreStaff (super_admin). Re-submit on an already-completed org record runs the same repair path. Historical rows missing centre staff are backfilled via deploy command repair:organisation-centres — Console commands.

  • After Orchestrator Auth, the client calls CAP GET /onboarding/mine (always 200, possibly empty) and GET /me for hats. Login does not carry onboarding.
  • Candidate onboarding remains the SoT for application-draft personal/occupation fields. After submit, unlocked occupation and accessibility edits go through PATCH /me/profile (same blob) — not a second flatten on dashboard DTOs. Persona profile GETs (/candidate/profile, /assessor/profile, /centre/profile) nest the full OnboardingRecord so settings do not need a second onboarding GET. Nested data stays id-only (no resolved URLs inside the blob). Profile photo is not in onboarding JSON — it is CapUser.photoAssetId.
  • Invite creates a staff draft if missing, prefilled from completed candidate onboarding when present.
  • NIN: required for staff-only accounts on staff submit; skipped if identityVerified is already true.
  • Staff payload: personalDetails, contactInformation, residentialAddress, acknowledgements.acceptsCentreStaffTerms. Email should match the OL account.
  • Assessor payload (AssessorOnboardingPayload): personal/contact/address plus assessorDetails (assessorNo, optional sectorIds, optional resumeAssetId, certifications). Professional cert slots are ev / qaa / iqm (submit requires ≥1). Optional certifications.rpl is a supporting document only — it does not derive qualifications and does not satisfy the ≥1 rule. Resume and cert asset IDs are stored in the onboarding blob; resolved URLs appear on AssessorSnapshot (resume, certificates[]) for admin and self profile GETs.

See openapi/cap.yaml. POST /onboarding/start is idempotent per (capUser, persona). Completeness on submit follows variant for centre. After COMPLETED, PATCH /onboarding/{persona}/save stays 409. Personal contact/address/occupation/accessibility/photo edits go to PATCH /me/profile (occupation and accessibility require a candidate onboarding record — 422 profile.candidate_onboarding_required otherwise). Centre org fields (logo, optional accreditation certificateAssetId, optional tradeIds, support, bank, address) go to organisation onboarding save/submit and later PATCH /centre/profile (super_admin). tradeIds and certificateAssetId are optional (not completeness-gated). registrationNo is locked once the Centre row exists. There is no PATCH /candidate/profile.