Suppliers
The supplier register lets committees build and maintain a list of approved contractors for each scheme. Each supplier entry tracks licence details, compliance status across four standard checks, and an anonymous cross-scheme rating. NSW schemes can verify licences directly against NSW Fair Trading in real time.
Data model
There are two levels of supplier data:
- Supplier (global) — the contractor's identity: business name, licence number, ABN, contact details. Shared across all schemes that use that contractor. Updated with fresh data from NSW Fair Trading each time a licence lookup is performed.
- SchemeSupplier (scheme-scoped) — the link between a supplier and a specific scheme. Holds scheme-specific data: notes, approved status, compliance checks, and the scheme's rating.
When a committee adds a supplier that already exists in StrataSphera (matched by licence number or ABN), the global record is reused. No duplicate entries are created; the committee simply links to the existing global record.
Adding a supplier
The Add Supplier form offers a quick-search lookup before manual entry:
- Enter a licence number or ABN in the quick-search field.
- The system queries the StrataSphera network and (for NSW schemes with a licence number) NSW Fair Trading concurrently. Both sources are checked in parallel — NSW wins for live identity data; StrataSphera fills contact and enrichment fields.
- If found, the form pre-fills. For NSW schemes, a live status badge is shown.
- If the supplier is already in your scheme, an amber warning blocks the add — the committee must remove the existing link first.
- If not found, the form can be filled manually. The new supplier record is created in the global database and linked to your scheme.
| Field | Scope | Notes |
|---|---|---|
business_name | Global | Required. Canonical trading name. |
licensee_name | Global | Individual licence holder if different from business name. |
licence_number | Global | Used for NSW Fair Trading lookup. Unique index. |
licence_type | Global | Electrical, plumbing, building, etc. |
licence_expiry_date | Global | Populated from NSW Fair Trading. Displayed with red/amber warning near expiry. |
nsw_verified_at | Global | Timestamp of last NSW Fair Trading check. Shown on detail page. |
abn | Global | Digits only (whitespace and non-digits stripped on save). |
suburb / postcode | Global | Populated from NSW Fair Trading where available. |
notes | Scheme | Private note visible only within the scheme. |
is_approved | Scheme | Committee approval flag. Defaults to true on add. |
NSW Fair Trading integration
For NSW schemes, licence searches call the NSW Government Trades Register API (api.onegov.nsw.gov.au/tradesregister/v1/verify). This returns live licence status, expiry date, licensee name, suburb, postcode, and associated business names.
The integration uses OAuth 2.0 client credentials. A cached access token is reused across requests and refreshed automatically when it expires. The backend stores three fields from each successful verification:
licence_expiry_date— parsed from the NSW response (format:dd/MM/yyyy)nsw_licence_id— the NSW-internal ID, retained for future lookup callsnsw_verified_at— timestamp of the verification, so data freshness is visible
Live licence status is deliberately not cached — it can change between lookups and is only shown during an active search, not on the supplier detail page.
ABN-only searches skip the NSW API. The NSW lookup fires only when a licence number is supplied and the scheme's jurisdiction is nsw.
Compliance checks
When a supplier is added to a scheme, four compliance check rows are automatically created inpending status. Committee members can update each check independently.
| Check type | What it verifies |
|---|---|
licensed | The supplier holds a current licence appropriate to the type of work. |
insured_liability | Supplier holds public liability insurance (minimum $20M recommended for strata work). |
insured_workers_comp | Supplier holds workers compensation insurance covering all employees and contractors. |
correct_contract | Supplier uses an appropriate contract for the scale of work (e.g. AS 4000 for major works). |
Each check has the following statuses:
| Status | Meaning |
|---|---|
pending | Not yet checked. Default when supplier is added. |
verified | Check passed. Records who verified it and when. |
failed | Check failed (e.g. insurance lapsed). |
expired | Previously verified but the document has since expired. |
not_required | Not applicable for this supplier or work type. |
Setting a check to verified automatically records verified_by andverified_at from the authenticated user and server timestamp.
PDF document attachments
Each compliance check supports one attached PDF document (e.g. a certificate of currency, licence printout, or contract copy). Documents are stored in a private Supabase Storage bucket (supplier-compliance) and accessed via short-lived signed URLs (1-hour expiry).
- Maximum file size: 10 MB per document.
- Only PDF files are accepted (
application/pdf). - Uploading a new document replaces the previous one automatically.
- The document name and size are stored on the compliance check row.
- Viewing a document calls
GET .../compliance/{checkType}/documentwhich returns a signed URL. This is available to all scheme members (not just committee). - Deleting a document requires committee access.
Ratings
Each scheme can submit one rating (1–5 stars) plus an optional review for each supplier they use. Ratings are:
- Scheme-specific — each scheme's rating is private to that scheme.
- Aggregated anonymously — the global average and count are visible to all schemes viewing the supplier. No scheme can see another scheme's individual rating or review text.
Only committee members can submit or update a rating. The rating widget is on the supplier detail page and allows editing at any time.
API reference
| Endpoint | Auth | Notes |
|---|---|---|
GET /api/suppliers/lookup | Any member | Search by licence_number or abn. Pass scheme_id to enable duplicate detection and NSW lookup. Returns { supplier, already_in_scheme, nsw_verification }. |
GET /api/schemes/{schemeId}/suppliers | Member | Paginated list of scheme suppliers with compliance summary and ratings. |
POST /api/schemes/{schemeId}/suppliers | Committee | Add a supplier to the scheme. Triggers NSW Fair Trading lookup for NSW schemes. |
GET /api/schemes/{schemeId}/suppliers/{schemeSupplierId} | Member | Full supplier detail including all compliance checks and ratings. |
PUT /api/schemes/{schemeId}/suppliers/{schemeSupplierId}/compliance/{checkType} | Committee | Update a compliance check status, expiry date, and notes. |
POST .../compliance/{checkType}/document | Committee | Upload a PDF. Multipart form data, field name file. Max 10 MB. |
GET .../compliance/{checkType}/document | Member | Returns a 1-hour signed URL for the attached PDF. |
DELETE .../compliance/{checkType}/document | Committee | Remove the attached document. |
POST .../rating | Committee | Submit or update the scheme's rating (1–5) and optional review text. |
DELETE /api/schemes/{schemeId}/suppliers/{schemeSupplierId} | Committee | Remove the supplier from the scheme (does not delete the global supplier record). |
Business rules
- Only committee members can add, update, or remove suppliers and compliance data.
- A supplier cannot be added to a scheme more than once. The API returns HTTP 409 on duplicate add.
- The global supplier record (name, licence, ABN) is shared across schemes. NSW Fair Trading data is written back to the global record on every lookup so all schemes benefit from fresh data.
- The
suppliersfeature is included on every plan (and during the 30-day trial). Like all writes, it is blocked once a scheme is past its trial without payment (statusexpired). - Removing a supplier from a scheme does not delete the global supplier record or any other scheme's link to that supplier.