Supplier Onboarding and Qualification

The control flow a finance team actually needs.

The ERP surface involved.

Sanctions screening must complete within 10 seconds of submission using an integrated third-party screening service; deduplication must match on legal name, tax ID, and bank account with configurable fuzzy-match threshold; document storage must accept PDF/JPEG/PNG up to 20 MB per file; supplier portal must be accessible without internal SSO (public-facing with invite token); audit trail must record every status change with actor, timestamp, and document version; bank account details must be encrypted at rest (Privacy Vault).

US and UK teams have different compliance hooks, but the same control problem.

US teams usually care about clean evidence for audit support, vendor records, payment controls, tax reporting, and management review. UK teams usually care about VAT-ready records, approval evidence, digital-record discipline, and traceable postings. The country-specific details differ, but the operating pattern is the same: the ERP needs controlled records, explicit ownership, defensible state changes, and evidence that survives beyond the person who completed the task.

The control matrix.

Audit evidence is a chain, not a folder.

supplier { id: string, legal_name: string, tax_id: string, country: string, status: enum, tier: enum, payment_terms: string, external_id: string };
supplier_document { id: string, supplier_id: string, doc_type: string, file_ref: string, version: int, uploaded_at: timestamp };
sanctions_screen_result { id: string, supplier_id: string, screened_at: timestamp, result: enum, service_response_payload: jsonb, cleared_by_1: string, cleared_by_2: string };
supplier_bank_account { id: string, supplier_id: string, account_details_encrypted: string };
(reference, product may differ).

POST /v1/suppliers/onboarding { legal_name, tax_id, country, bank_account, certifications[], categories[], contact } -> 201 { id, status, sanctions_result };
POST /v1/suppliers/{id}/activate -> 200;
GET /v1/suppliers/{id}/sanctions-history;
emits supplier.onboarding_submitted, supplier.sanctions_screened, supplier.activated events;
idempotent via external_id.

PENDING_SUBMISSION -> PENDING_COMPLIANCE_REVIEW -> ACTIVE;
exception path PENDING_COMPLIANCE_REVIEW -> SANCTIONS_HOLD -> CLEARED (two-person sign-off required);
terminal REJECTED, DEACTIVATED;
guard: ACTIVE→DEACTIVATED blocks new PO/payment/receipt posting;
sanctions re-screen on legal name/country/ownership change.

The useful version of this workflow is not only fast. It is inspectable. A controller, auditor, or operator should be able to move from source event to system record to state transition to final business outcome without guessing.

Implementation contracts.

`supplier` { id: string, legal_name: string, tax_id: string, country: string, status: enum, tier: enum, payment_terms: string, external_id: string }; `supplier_document` { id: string, supplier_id: string, doc_type: string, file_ref: string, version: int, uploaded_at: timestamp }; `sanctions_screen_result` { id: string, supplier_id: string, screened_at: timestamp, result: enum, service_response_payload: jsonb, cleared_by_1: string, cleared_by_2: string }; `supplier_bank_account` { id: string, supplier_id: string, account_details_encrypted: string }; (reference, product may differ).

`POST /v1/suppliers/onboarding` { legal_name, tax_id, country, bank_account, certifications[], categories[], contact } -> 201 { id, status, sanctions_result }; `POST /v1/suppliers/{id}/activate` -> 200; `GET /v1/suppliers/{id}/sanctions-history`; emits `supplier.onboarding_submitted`, `supplier.sanctions_screened`, `supplier.activated` events; idempotent via `external_id`.

`PENDING_SUBMISSION -> PENDING_COMPLIANCE_REVIEW -> ACTIVE`; exception path `PENDING_COMPLIANCE_REVIEW -> SANCTIONS_HOLD -> CLEARED (two-person sign-off required)`; terminal `REJECTED`, `DEACTIVATED`; guard: ACTIVE→DEACTIVATED blocks new PO/payment/receipt posting; sanctions re-screen on legal name/country/ownership change.