Network onboarding

This page sets out the AR data import process, which is Step 3 of the principal-firm adoption path. The import takes the firm’s existing AR network (typically held in a spreadsheet, a CRM, or an off-the-shelf network-management tool) and lands it in the workspace as appointed_reps rows ready for supervision.

CSV template

The operator provides a CSV template at adoption. The columns map directly to the AppointedRep data shape:

Column	Required	Type	Validation	Notes
tradingName	yes	string	min 2 chars, max 200	The AR’s trading name as registered
legalName	yes	string	min 2 chars, max 200	The AR’s legal name where different from trading name
frn	conditional	string	6 or 7 digits, regex ^\d{6,7}$	Required for AR (full appointed representative); IARs share the principal’s FRN, leave blank
type	yes	enum	AR or IAR	Introducer Appointed Representative or full AR
status	yes	enum	active, suspended, under-investigation, terminated	Initial status; usually active at import
permissions	yes	string	semicolon-separated permission codes	e.g. MCOB.ARRANGE;MCOB.ADVISE for a mortgage AR; codes are vertical-specific
registeredOffice.line1	yes	string	max 200
registeredOffice.line2	no	string	max 200
registeredOffice.city	yes	string	max 100
registeredOffice.postcode	yes	string	UK postcode regex	^[A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2}$
appointedOn	yes	ISO date	YYYY-MM-DD	Date of AR appointment
lastAnnualReviewAt	no	ISO date	YYYY-MM-DD	Most recent annual review; empty if never reviewed
isSelfEmployed	yes	boolean	true or false	PS22/11 flag for self-employed AR-individuals
supportsImportantBusinessService	yes	boolean	true or false	SYSC 15A flag
principalContactEmail	yes	string	RFC 5322 email	The principal-side compliance officer assigned to this AR
arUserEmail	conditional	string	RFC 5322 email	The AR-user account to invite (one per AR; multiple via separate rows in the user-invitation table)
notes	no	string	max 1000	Free-text notes for the principal-side record

The CSV is UTF-8, with , as the field delimiter and " as the quote character. Header row is required. The order of columns follows the table above.

A sample CSV with five fictional ARs ships with the template. The operator runs through the sample with the firm’s compliance lead in the adoption call.

Validation

The import handler validates each row against the Zod schema (AppointedRepImportSchema, derived from AppointedRep minus the system-managed fields). The handler runs in two passes:

1. Per-row syntactic validation. Type checks, regex checks, enum membership. Rows that fail are flagged with the column name and the failure reason. The handler shows the validation report before any rows are persisted.
2. Cross-row and reconciliation checks. Detects duplicate FRNs (an FRN cannot appear twice in the firm’s network), duplicate trading names, AR-user email collisions across ARs (one AR-user per email), and ARs with type=AR and a missing or invalid FRN.

The firm fixes the validation report in its source spreadsheet and re-uploads. The handler is idempotent on (tradingName, frn); a re-upload that fixes errors does not duplicate already-imported rows.

FCA Register reconciliation

Each row with a non-blank frn is reconciled against the FCA Register via the FCA’s public API. The reconciliation checks:

• The FRN exists on the Register.
• The FRN is registered as an Appointed Representative.
• The legalName matches the Register’s registered name (within tolerance for whitespace and casing).
• The principal firm on the Register matches the firm running the import. A mismatch is a hard error; the operator does not allow a firm to import an AR that is not registered against it.
• The AR’s permissions on the Register are a superset of the permissions column. A row that claims permissions the FCA Register does not show is flagged.

Reconciliation findings appear in the import report alongside the syntactic validation errors. A firm with 200 ARs typically has 5 to 15 reconciliation flags on the first import, mostly for whitespace and casing differences in legal names. The firm corrects the source data and re-uploads.

The FCA Register is updated overnight; an AR appointed in the last 24 hours may not yet be visible. The handler treats “FRN not yet on Register” as a soft warning, not an error, and writes the AR row with a pending-fca-register flag for compliance review.

IBS designation

The supportsImportantBusinessService flag (SYSC 15A) is the firm’s own assessment, not an FCA Register fact. The flag indicates whether failure of the AR would cause intolerable harm to the firm’s customers or to the wider market.

The operator surfaces a guidance link to the FCA’s SYSC 15A material at the import step. The flag is set per AR by the firm; the firm’s SMF16 reviews and signs off the IBS register at adoption, with a quarterly review thereafter.

ARs with supportsImportantBusinessService=true appear in a dedicated dashboard tile on the principal-side home and have a higher minimum file-review cadence by default (quarterly rather than annual).

PS22/11 self-employed flag

The isSelfEmployed flag is set per AR-individual, not per AR firm. For an AR firm with a single AR-individual operating as a sole trader, the flag is true. For an AR firm with multiple individuals, the flag follows the predominant working pattern and the firm’s own conduct-risk assessment.

ARs with isSelfEmployed=true are subject to the enhanced principal-oversight regime introduced by PS22/11 (December 2022). The workspace surfaces these ARs in a dedicated filter and applies a higher default risk-score weighting on the time-since-last-review input.

Rubric assignment per AR

The default rubric for each AR is inherited from the tenant’s vertical (MCOB for mortgage, ICOBS for general insurance, CONC for credit broking). Where an AR holds permissions across multiple verticals (a mortgage broker that also arranges general insurance, for example), the firm assigns a per-AR rubric override:

• The AR’s primary rubric (used for the default file-review template).
• Optional secondary rubrics that the firm wants the file review to additionally score against.

The rubric assignment is held on the appointed_reps.rubric_override JSONB column. The default rubric remains available; the override only adjusts the file-review template.

Import audit

Each row imported writes an ar.created audit event with the principal-admin actor, the import batch id, and the source CSV row number. A re-upload that updates an existing AR writes ar.updated events with the diff. The import batch itself is an audit event (ar.import-batch) with the file SHA-256 and the row count.

A failed import (validation errors that the firm chose not to fix) writes ar.import-batch-failed with the error count.

Editing after import

Post-import, AR records are editable by principal-admin and (with limits) principal-compliance-officer roles. The RBAC matrix in threat model sets out the per-field write scope. Off-boarding an AR (status to terminated) is a terminal action requiring step-up authentication and writes ar.terminated to the audit chain with the actor and the second-factor event id.

The firm’s view of the AR register is filterable, sortable, and exportable; the export itself is rate-limited (5 per hour per session) and audit-logged. Detail in rate limiting.

Operational notes

A typical import for a 124-AR mortgage network completes in under 30 minutes including reconciliation. A 200-AR credit-broking network takes 1 to 2 hours including reconciliation flag fixes. Networks above 500 ARs are handled with the operator on the call to walk through the validation report.

Reconciliation against the FCA Register is rerun nightly for the workspace. ARs whose Register status changes (a permission is added or revoked, the AR’s legal name is updated, the AR is removed from the Register) raise a flag in the principal-side workspace the next morning, with a one-click acknowledgement that records the fact and the actor.