Ark Flows API — endpoints

Six public endpoints drive onboarding: one start + one status per flow (individual, sole-trader, company). The formal request/response schema is the Ark Onboarding API OpenAPI specification (openapi/source/platform/onboarding/onboarding.yml) — this page covers how to call each one; it does not restate the schema.

Method	Path	Purpose
POST	/v1/onboarding/individual	Start an individual onboarding
GET	/v1/onboarding/individual/{workflowId}/status	Read an individual onboarding's state
POST	/v1/onboarding/sole-trader	Start a sole-trader onboarding
GET	/v1/onboarding/sole-trader/{workflowId}/status	Read a sole-trader onboarding's state
POST	/v1/onboarding/company	Start a company onboarding
GET	/v1/onboarding/company/{workflowId}/status	Read a company onboarding's state

The status routes share an identical response envelope; only the start routes' request bodies differ.

Authentication and tenant headers

Every call requires:

What	How
Bearer token	Authorization: Bearer <token> — an OAuth2 access token (Entra ID).
clientid	Header identifying the Ark client (tenant).
brandid	Header identifying the brand within that client.

Errors use the standard Ark error envelope (an error code plus a message).

Start an individual onboarding

POST /v1/onboarding/individual

Starts the onboarding and returns immediately — the journey runs in the background.

Request body — StartIndividualOnboardingRequest

Field	Required	What it is
party	✓	The individual applicant: identity details, phone numbers, email addresses, and at least one address. entityType is INDIVIDUAL.
documents	✓	Identity documents to submit for verification (e.g. driver's licence, passport).
productKey	✓	The account product to open (SAVINGS / TRANSACTION, or an Ark product id).
productVersion	✓	Version of the selected product (e.g. 1.0.0).
cardType	✓	Card to issue: PHYSICAL, VIRTUAL, or PHYSICAL_AND_VIRTUAL.
riskScoringContext		Applicant-disclosed facts the risk assessment needs that Ark can't derive from party (e.g. PEP status, source of wealth). Optional; all sub-fields optional.

Start a sole-trader onboarding

POST /v1/onboarding/sole-trader

Same envelope as the individual start, with the applicant flagged as a sole trader on the party.

Request body — StartSoleTraderOnboardingRequest

Same shape as StartIndividualOnboardingRequest. The flow-specific differences live inside party:

• party.entityType is SOLE_TRADER.
• party.entityDetails carries abn (required) plus optional tradingName and industryCode.

Everything else (documents, productKey, productVersion, cardType, riskScoringContext) is identical to the individual flow.

Start a company onboarding

POST /v1/onboarding/company

Onboards a company. The caller provides the company party plus references to existing director parties and one signatory.

Request body — StartCompanyOnboardingRequest

Field	Required	What it is
party	✓	The company party (entityType: COMPANY) including entityDetails, addresses, phones, emails, and relationships[] — caller-supplied partyIds for existing directors.
documents	✓	Identity documents to submit for verification.
productKey	✓	The account product to open.
productVersion	✓	Version of the selected product.
cardType	✓	Card to issue.
signatory	✓	A single signatory block ({ partyId, relationshipCode }) pointing at a previously-onboarded individual party that will be linked to the company's account once it is created. The MVP supports one signatory; future tickets may widen to N>1.
riskScoringContext		Applicant-disclosed facts the risk assessment needs that Ark can't derive from party. Optional.

Address handling (all three flows)

Within each party address, only the free-text addressLine is needed — Ark resolves it to a canonical delivery-point address itself, so a caller-supplied dpid is accepted but ignored.

Response — 202 Accepted

The body is a WorkflowStateResponse wrapping the initial state (status: INITIATED, results: []). A Location header points at the status endpoint to poll.

HTTP/1.1 202 Accepted
Location: /v1/onboarding/individual/123e4567-e89b-12d3-a456-426614174000/status

{
  "workflowState": {
    "workflowId": "123e4567-e89b-12d3-a456-426614174000",
    "workflowType": "individual",
    "status": "INITIATED",
    "currentStep": "initialisation",
    "createdAt": "2026-05-27T10:00:00.000Z",
    "updatedAt": "2026-05-27T10:00:00.000Z",
    "errors": [],
    "results": []
  }
}

workflowType matches the path (individual / sole-trader / company). workflowId is the handle to track this onboarding — use it in the status call.

Errors (any start endpoint)

Status	When
401	Missing or invalid bearer token.
400	Request body fails schema validation (GEN000000).
500	Internal error while starting the onboarding.

Get onboarding status

GET /v1/onboarding/{flavour}/{workflowId}/status

where {flavour} is individual, sole-trader, or company. {workflowId} is the id returned by the matching start call. Poll this to follow the onboarding through its states (see lifecycle).

The path's {flavour} segment is not cross-validated against the row's workflowType — polling a sole-trader workflow via the /individual/.../status route returns the row. Branch on the response's workflowType field, not the URL.

Response — 200 OK

A WorkflowStateResponse wrapping the current WorkflowState:

Field	What it is
workflowId	The onboarding id.
workflowType	individual, sole-trader, or company.
status	High-level state: INITIATED, IN_PROGRESS, PENDING_ACTION, COMPLETED, or FAILED.
currentStep	A granular progress label for the step in flight (e.g. validateAddress, scoreRisk, provisioning, completed).
createdAt / updatedAt	Timestamps.
errors	Messages collected during the onboarding (populated when something fails). Never contains raw applicant data.
results	One entry per step that has run so far, each with its status (running / completed / failed) and a sanitised output.

Each result's output is sanitised before it leaves Ark — sensitive details (access tokens, full street addresses, raw verification notes) are stripped, leaving only the identifiers and outcomes a caller needs. For example, the risk-assessment result exposes a score, a riskLevel (LOW / MEDIUM / HIGH), and a sendForReview flag, and the provisioning result exposes the created party, account, and card identifiers (plus, for company onboardings, the linked signatory). The per-step output shapes are defined in the OpenAPI specification.

Errors (any status endpoint)

Status	When
401	Missing or invalid bearer token.
404	No onboarding exists for that workflowId (ONB004001).
500	Internal error reading the state.

---

An additional POST /v1/internal/workflow-state route exists for internal use only (Ark writes onboarding progress to it as the journey runs). It is not part of the caller-facing API.