Management Dashboard — Contractors & Onboarding

Contractors is your supply-chain directory: every contractor you work with, their trades, insurance and accreditations, and — since the contractor onboarding rework — one entry point that asks what kind of contractor you're adding, then offers every add path without ever blocking your work. Tiered — Basics for adding a contractor and sending work, Deep dive for the fork, the three external-firm add paths and account lifecycle, Technical for the security model.

---

Basics — add a contractor and send work the same day

1. Open Contractors from the sidebar.
2. Click + Add contractor. You're asked one question first — is this an external firm (they run their own HousingSurvey Pro organisation, or you set one up for them) or an in-house contractor surveyor (a sub-contractor with no account of their own, who signs in as one of your surveyors)? Pick one and the matching form opens; ← Choose again on any of the resulting forms returns to this question.
3. For an external firm, type the company name — email and phone are optional — and save. That's it: the contractor appears in your list and work orders can be sent to them immediately. Nothing about their own sign-up ever blocks you dispatching work.
4. Add full company detail (trades, regions, insurance and accreditation expiry dates — these drive automatic expiry warnings) any time by clicking the entry and editing it, or choose "Add full company details instead" from the external-firm form up front if you prefer.
5. Import CSV bulk-loads your supply chain from a procurement-system export (a separate toolbar button — it's a bulk path, not part of the fork above).

What the status chips mean

Chip	Meaning
Active	A contractor running their own HousingSurvey Pro account, linked to you.
Unclaimed	You added them (name only, or with credentials issued) and nobody at the contractor has taken the account over yet. Work orders still send normally.
Invited — awaiting validation	You added them with an email address; they've been emailed an invite and haven't picked it up yet. Work orders still send normally.
Credentials issued — unclaimed	You generated a sign-in for them (see below) and they haven't yet claimed the account as their own.
Suspended	You suspended them — no new work orders can be sent until you reactivate.

---

Deep dive — the fork, the three external-firm add paths, and the account lifecycle

The fork: external firm vs in-house contractor surveyor

+ Add contractor always asks this question first, rather than presenting several separately-labelled buttons — every destination below is still reachable, just one step further in:

• External firm — they use HSP. The contractor runs their own HousingSurvey Pro organisation. They manage their own surveyors, insurance and accreditation records; work you send them is ring-fenced to their own account. This branch leads to the three add paths below.
• In-house contractor surveyor — they work for you. For a sub-contractor with no HSP account of their own. You fill in their name, the contractor firm they work for, and (optionally) their own email — this creates a normal surveyor login inside your own organisation (consuming one of your surveyor seats), tagged with the firm label so more than one surveyor can share it. There's no invite, subscription or claim step for them at all: a generated sign-in is shown once for you to hand over, exactly like "Issue sign-in credentials" below, just as the direct next step of this form. Requires member-management permission.

1. Blind add (name only)

For an external firm with no usable email — or when you just want them on the books now. Type the name, save, done. No email is ever sent. The chip reads Unclaimed until someone at the contractor takes the account over.

2. Invite (email present)

Exactly the same as blind add, plus an invite email to the address you gave (sent through your organisation's own SMTP if configured under Settings, otherwise the platform sender). The chip reads Invited — awaiting validation, with Resend invite and Revoke invite actions on the card. Revoking the invite does not remove the contractor — they simply drop back to Unclaimed.

3. Issue sign-in credentials

For the external firm whose "email" is a personal Gmail they never check — or who has none at all. Issue sign-in credentials (reached via "Issue sign-in credentials instead" from the external-firm form) generates a ready-made sign-in you hand to them yourself:

• The sign-in email is either their own address (if you enter one) or an internally generated placeholder email. The generated address has no mailbox — nothing is ever emailed to it; you give the contractor the email + password directly (phone, in person, a password-manager share).
• The password is generated for you, shown once, and never stored — copy it before closing the panel. Lost it? Regenerate credentials rotates it (the old one stops working immediately).
• On their first sign-in — portal or field app — the contractor is required to set their own password before anything else loads.
• Revoke credentials disables the sign-in entirely (and is audited), without removing the contractor from your list.

Claiming — how "Unclaimed" becomes "Active"

Every contractor you add this way gets its own separate organisation on the platform — it was never inside yours. When a real person at the contractor engages properly, they claim it:

1. They sign in (with issued credentials, or by signing up with the invite).
2. Under Settings → My account they add their own email address and click the verification link we send to it.
3. On their next sign-in, the account is automatically marked claimed — your chip clears to Active, and from that moment the account is theirs alone: you can no longer revoke or regenerate its credentials.

Nothing you or they do during claiming interrupts work orders already in flight.

Limits and housekeeping

• You can hold at most 25 unclaimed contractor shells at a time — a hygiene ceiling, not a business limit (claimed contractors don't count). If you hit it, get one claimed or remove one.
• Suspending a contractor (in the edit panel) stops new work orders without touching their data or their account.
• Every action here — adding, inviting, issuing, regenerating, revoking, claiming — lands in your organisation's tamper-evident audit log.

---

Technical — the security model

• Contractors are always separate organisations, linked to yours by a grant record. A contractor you add blind is created as a shell organisation (a server-set lifecycle state of "unclaimed", stamped with your org as creator) — outsiders are never made members of your organisation, so the cross-tenant boundary (they see only their own work, never your stock or other contractors' evidence) holds by construction from day one.
• The grant is bound and active at creation for all three add paths, which is what makes work orders sendable immediately — validation was redesigned as a claim rather than a gate.
• Landlord-issued accounts carry a flag requiring the contractor to set their own password on first login; both apps block first sign-in on an inline change-password step, and only a server call (after a successful password change) clears it.
• The platform-generated sign-in addresses are flagged internally as placeholder addresses on the member record; every email fan-out on the platform either takes an explicit recipient or filters out these placeholder addresses — no system path ever attempts delivery to one of them.
• Claiming requires a verified email on the signed-in account (Identity Platform's email-verified status, never client-asserted) that is not a placeholder address; the lifecycle flip happens server-side only. Once claimed, the creating landlord's revoke/regenerate paths are refused — a landlord can never lock an independent business out of its own account.
• Contractor surveyor seats belong to the contractor's own organisation (shells start on the free Solo tier, one seat), never to the landlord's licence. Unclaimed shells are excluded from platform revenue metrics. This is distinct from the in-house contractor surveyor fork above, which is deliberately the opposite: no separate organisation is created at all, and the login consumes one of the landlord's own surveyor seats, the same as any of the landlord's own staff.