Sole-trader onboarding

The end-to-end journey for a SOLE_TRADER applicant — a single person operating a sole-trader business identified by an ABN. A caller starts the onboarding with one request and then polls its status; Ark runs the whole journey in the background.

The request body is StartSoleTraderOnboardingRequest:

Field	What it carries
party	The applicant (entityType: SOLE_TRADER): identity details, phones, emails, at least one address, and an entityDetails block carrying abn (required) plus optional tradingName and industryCode.
documents	Identity documents to submit for verification (e.g. driver's licence, passport).
productKey	The account product to open.
productVersion	Version of that product.
cardType	Card to issue (PHYSICAL, VIRTUAL, or PHYSICAL_AND_VIRTUAL).
riskScoringContext	Optional applicant-disclosed facts the risk rule can't derive from party (e.g. PEP, source of wealth).

For how the three onboarding flows compare, see the onboarding overview.

States

The onboarding reports a high-level status plus a granular currentStep at every point.

Status	Meaning
INITIATED	Accepted by the API; not yet executing. This is the status returned by the start call.
IN_PROGRESS	Steps are executing (address validation, risk assessment, provisioning).
PENDING_ACTION	Waiting on identity verification — in particular a manual review, which can take up to ~3 days.
COMPLETED	Terminal success — the party, account, and card have been provisioned.
FAILED	Terminal failure — a step failed, identity was not verified, or the risk assessment was not LOW. The reason is on the state's errors.

The journey

1. Validate the address. The applicant's free-text addresses[0].addressLine is resolved to a canonical delivery-point address in two calls: a PAF autocomplete lookup picks the best-match address id, then a metadata call resolves that id to the full canonical record (dpid, street, locality, postcode, state). This canonical address — not the caller's raw text — is what Ark uses for the rest of the journey. Any dpid the caller supplied is ignored and re-derived here.

2. Verify identity (KYX) — sent as INDIVIDUAL on the wire. The identity check for a sole trader is the same person-level verification as an individual (firstName / lastName / dateOfBirth), so the initiateKyx activity detects SOLE_TRADER and builds an individual KYX request from entityDetails. This is deliberate: the platform's POST /v1/parties/kyx rejects entityType: SOLE_TRADER with 501 NOT_IMPLEMENTED, so the activity sends INDIVIDUAL and the platform never sees SOLE_TRADER. The caller's party.entityType stays SOLE_TRADER everywhere else in the workflow envelope.

   Ark creates the verification record and party shell with the identity vendor (GreenID), receives a verification id, and uploads each item in documents against it. The onboarding moves to PENDING_ACTION and a polling loop watches the verification:

   • Clean applicants pass within minutes.
   • Others enter a manual review and stay PENDING_ACTION until the verification reaches a terminal outcome or the review window elapses. The loop polls every minute for the first 10 minutes, then hourly, with a hard cap of 3 days.
   • On VERIFIED the onboarding returns to IN_PROGRESS. Any other outcome — DECLINED, ERRORED, or a 3-day TIMEOUT — ends the onboarding as FAILED.

3. Assess risk. A business-rules risk assessment runs against the applicant's facts — what Ark can derive from party (citizenship, postcode, legal structure) merged with any disclosed riskScoringContext. The rule key is SOLE_TRADER_RISK_RULE_KEY, which in v1 resolves to risk-scoring-individual (a dedicated risk-scoring-sole-trader JDM is a follow-up; the scoreRisk step is already parameterised on rule key, so only the constant changes when the dedicated rule ships). Only a LOW result proceeds; a MEDIUM, HIGH, or unrecognised result ends the onboarding as FAILED and routes the applicant to manual review. Risk runs before provisioning, so a non-low outcome never leaves a half-provisioned party.

4. Provision party + account + card. For low-risk, verified applicants, Ark provisions, in order, the party, the account (per productKey / productVersion), and the card (per cardType) in core banking (UDA). The sole-trader fields (abn, and optional tradingName / industryCode) ride along on the party-provisioning call inside entityDetails and are forwarded onto the created party in core banking. The party becomes active at this step. Once the card is created the onboarding reaches COMPLETED.

Result

On success the workflowType on the response is sole-trader. The created partyId, accountId, cardId, and their core-system references are carried on the provisioning step's result (the provisioning entry in the state's results).