Company onboarding

The end-to-end journey for a COMPANY applicant — a company whose directors have already been onboarded as individual parties, one of whom will be the authorised signatory on the company's account. 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 StartCompanyOnboardingRequest:

Field	What it carries
party	The company (entityType: COMPANY): an entityDetails block with the company-level fields (name, ACN/ABN, jurisdiction), phones, emails, addresses, and relationships[] (see below).
relationships[]	(inside party) { relationshipType: 'DIRECTOR', relatedPartyId, effectiveFrom } entries pointing at already-onboarded individual parties.
documents	Identity documents to submit for verification.
productKey	The account product to open.
productVersion	Version of that product.
cardType	Card to issue (PHYSICAL, VIRTUAL, or PHYSICAL_AND_VIRTUAL).
signatory	A single { partyId, relationshipCode: 'AUTHORISED_SIGNATORY' } block pointing at an already-existing individual party. Linked to the company's account between account and card creation. The MVP supports one signatory; future tickets may widen to N>1.
riskScoringContext	Optional applicant-disclosed facts the risk rule can't derive from party.

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, signatory link, 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 company'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 / KYB) — sent as COMPANY on the wire. The platform accepts company-shape KYX (KYB) directly, so the initiateKyx activity builds a company request from entityDetails: businessName ← party.name, companyNumber ← entityDetails.acn, businessNumber ← entityDetails.abn, country ← entityDetails.jurisdiction.

   Ark creates the verification record and party shell with the KYB vendor (SimpleKYC), 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 cases 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 company's facts merged with any disclosed riskScoringContext. The rule key is COMPANY_RISK_RULE_KEY, which in v1 resolves to risk-scoring-individual (a dedicated risk-scoring-company JDM is a follow-up). Only a LOW result proceeds; a MEDIUM, HIGH, or unrecognised result ends the onboarding as FAILED and routes the case to manual review. Risk runs before provisioning, so a non-low outcome never leaves a half-provisioned party.

4. Provision party → account → signatory → card. For low-risk, verified cases, Ark provisions, in order:

   • the party — with the caller-supplied relationships[] linking it to the existing director parties;
   • the account (per productKey / productVersion);
   • the signatory link — addSignatories calls the platform's POST /v1/accounts/{accountId}/signatories with { partyId, relationshipCode, signatory: true } from the caller's signatory block, linking the authorised signatory to the new account;
   • the card (per cardType).

   Once the card is created the onboarding reaches COMPLETED.

Result

On success the workflowType on the response is company. 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), alongside a signatory confirmation block: { partyId, accountId, relationshipCode, signatory: true, statementMethod: 'PAPER' }.

statementMethod: 'PAPER' is a constant on this confirmation block today (future tickets may parameterise it). It is not part of the signatory link request — the addSignatories call sends only { partyId, relationshipCode, signatory: true }.

Prerequisites

The caller must onboard, before submitting the company request:

1. Each director that will appear in party.relationships[] — onboard each via POST /v1/onboarding/individual first and capture the returned partyId.
2. The signatory party — onboard via POST /v1/onboarding/individual first and capture its partyId for the signatory.partyId field.

If any referenced party does not yet exist when the company request runs, party provisioning rejects the relationships and the onboarding fails at step 4.