Platform — parties endpoints

How to call the platform party and KYX routes. The formal schema is the OpenAPI specification (Ark Party Management API, openapi/source/platform/parties/parties.yml); this page is the call contract. The consumer journeys are in parties and KYX.

All routes require a B2B JWT (bearer token) with CLIENT role. Two variants:

• No party context — token only; these routes do not require (or read) a partyid header.
• Party context — token plus a partyid header that must resolve to a party in one of the listed statuses. The path :partyId must equal the header-derived party (PAR000006 PARTY_ID_MISMATCH otherwise).

Route summary

Method	Path	Code	Auth (party status)	Purpose
GET	/v1/parties/search	200	No party context	Search parties (stateless query)
GET	/v1/parties/{partyId}	200	Party (ACTIVE)	Get party details
PUT	/v1/parties/{partyId}	200	Party (ACTIVE)	Update a party (full replace)
POST	/v1/parties/provision	200	No party context	Provision (create + activate) a party
DELETE	/v1/parties/{partyId}	204	Party (PROSPECT or ACTIVE)	Soft-delete a party
POST	/v1/parties/{partyId}/relationships	201	Party (ACTIVE)	Attach an INDIVIDUAL to a COMPANY
GET	/v1/parties/{partyId}/relationships	200	Party (ACTIVE)	List a company's relationships
DELETE	/v1/parties/{partyId}/relationships/{relatedPartyId}	204	Party (ACTIVE)	Remove a relationship
POST	/v1/parties/kyx	200	No party context	Initiate a KYX verification
GET	/v1/parties/kyx/{arkVerificationId}	200	No party context	Get KYX check status
POST	/v1/parties/kyx/{arkVerificationId}/documents	200	No party context	Submit a verification document
GET	/v1/parties/kyx/{arkVerificationId}/documents	200	No party context	List KYX document outcomes
GET	/v1/parties/kyx/{arkVerificationId}/documents/{documentId}	501	No party context	Not implemented (stub)
GET	/v1/parties/kyx/{arkVerificationId}/verification	200	Party (ACTIVE)	Retrieve detailed verification data

Entity types

entityType accepts INDIVIDUAL, COMPANY, and SOLE_TRADER on the provisioning, get, update, delete and search routes. TRUST and PARTNERSHIP exist in the spec and reference data but are not wired — see Parties lifecycle. SOLE_TRADER is wired everywhere except KYX initiation, which returns 501.

---

GET /v1/parties/search — search parties

Stateless search. The platform infers individual-vs-company from which query parameters are present — there is no entityType parameter.

Name	Type	Notes
firstName	string	Individual search. Must be paired with lastName.
lastName	string	Individual search. Must be paired with firstName.
middleName	string	Optional, only meaningful alongside firstName + lastName.
name	string	Company search.

Rules (enforced before routing):

• Provide either (firstName + lastName) or name, never both → 400 PAR000012.
• Provide neither → 400 PAR000011.

dateOfBirth appears only on the response, never as a query parameter. The response is the provider's PartySearchResponse, relayed verbatim.

GET /v1/parties/{partyId} — get party details

Returns a PartyResponsePlatformApi. The party must exist in the caller's tenant and be a wired entity type (404 PAR004001 if absent; 409 PAR009004 if TRUST/PARTNERSHIP). The public entityType is taken from the platform record. Notable response shaping:

• Phone countryCode is always +61 (Australian).
• A COMPANY returns only { acn, abn } under entityDetails — companyType, incorporationDate and jurisdiction are not returned in this phase.

PUT /v1/parties/{partyId} — update a party

Full-replace (PUT) semantics. Body is a PartyUpdateRequestPlatformApi discriminated on entityType (INDIVIDUAL / COMPANY / SOLE_TRADER). Required identity fields per type are enforced per type (400 GEN000000 if missing). TRUST/PARTNERSHIP → 409 PAR009004. Returns the re-read party (a single resolve covers both the write and the read-back).

POST /v1/parties/provision — provision a party

Creates a party and drives it to ACTIVE in one call. Body is a PartyCreationRequestPlatformApi (INDIVIDUAL | COMPANY | SOLE_TRADER, each with its own entityDetails).

Response — PartyProvisionResponsePlatformApi:

{
  "partyId": "8e962b2d-d236-cbd1-9e90-ff9c84b28806", // platform party id
  "status": "ACTIVE",
  "vendorId": "43b8a730-20b3-42ef-946f-be3b1415a5ee", // provider-side id
}

Retry semantics. Provisioning runs more than one step. If a later step does not complete after the party is already ACTIVE, follow-up calls may return 404 until it is reconciled. Re-issuing the same POST /v1/parties/provision is safe — it is idempotent.

DELETE /v1/parties/{partyId} — soft-delete a party

Soft-deletes the party (sets deleted = true, status → TERMINATED). Pure platform DB operation — no provider call, no routing. Allowed when the party is PROSPECT or ACTIVE. Returns 204 No Content.

---

Relationships

Relationships attach an INDIVIDUAL party (the member) to a COMPANY party (the path partyId). All three routes are scoped to the company identified by partyId.

POST /v1/parties/{partyId}/relationships — attach a member

Body:

Field	Type	Required	Notes
relatedPartyId	UUID	✓	The INDIVIDUAL party to attach.
relationshipType	RelationshipType	✓	e.g. DIRECTOR, SHAREHOLDER, BENEFICIAL_OWNER, …

Validation (platform-side, fail-fast, before the provider call):

• partyId === relatedPartyId → 400 PAR000013 (a party cannot be linked to itself).
• The path party must be a COMPANY in the caller's tenant — otherwise 404 PAR004001.
• relatedPartyId must be an INDIVIDUAL in the caller's tenant — otherwise 404 PAR004001.

The wrong-entity-type rejection is deliberately a 404 (not a 409): a non-COMPANY path party or non-INDIVIDUAL related party is treated as "not found for this operation". Returns 201 with the provider's PartyRelationshipResponse.

GET /v1/parties/{partyId}/relationships — list

Returns the company's relationships (PartyRelationshipPlatformApi[]).

DELETE /v1/parties/{partyId}/relationships/{relatedPartyId} — remove

Removes a single relationship from the company. Returns 204 No Content.

---

KYX (Know Your X)

KYX is a verification-session system that is separate from a party's lifecycle — it never mutates party status, and POST /v1/parties/kyx creates no party record. A KYX session is identified by an arkVerificationId (the checkId returned by initiate) and is handled throughout by the provider that initiated it. The full journey and status tables are in KYX lifecycle.

POST /v1/parties/kyx — initiate a verification

Body is an InitiateKYXCheckRequestPlatformApi discriminated on entityType:

• INDIVIDUAL → a KYC person check (name, email, dateOfBirth, address).
• COMPANY → a KYB business check (businessName, companyNumber, businessNumber, country, referenceId, entityType).
• SOLE_TRADER → rejected with 501; KYX is not yet wired for sole traders.

Address handling for individuals is strict: the provider only accepts a default RESIDENTIAL, current address with no validity window. Supplying purpose ≠ RESIDENTIAL, isPreferred = true, isCurrent = false, or validFrom/validTo → 400 PAR000008. An omitted prefix defaults to Mx.

Response — InitiateKYXCheckResponsePlatformApi:

{
  "data": {
    "checkId": "8e962b2d-d236-cbd1-9e90-ff9c84b28806", // use as arkVerificationId
    "status": "IN_PROGRESS",
    "dateCreated": "2026-05-24T03:21:00.000Z",
    "vendorId": "43b8a730-20b3-42ef-946f-be3b1415a5ee",
  },
  "vendorId": "43b8a730-20b3-42ef-946f-be3b1415a5ee",
}

GET /v1/parties/kyx/{arkVerificationId} — get status

Returns { data: { checkId, dateCreated, status } }. status is one of the KYX verification statuses (IN_PROGRESS, VERIFIED, UNDER_REVIEW, FAILED, ERRORED, DECLINED, INCOMPLETE); an unrecognised provider value raises 422 PAR022001. See KYX lifecycle.

POST /v1/parties/kyx/{arkVerificationId}/documents — submit a document

Body is a DocumentUploadRequestPlatformApi carrying exactly one of:

• identityDocument — an identity document accepted by the verification provider (type, region, country, documentDetails, optional extraData). type is PASSPORT, DRIVERS_LICENCE, or NATIONAL_HEALTH_ID.
• fileUpload — a document in the document-based verification format (applicationId, file, documentType, cn, bn, pcn, other, associatedEntityName).

If neither is present → 400 GEN000000. Returns a DocumentResponsePlatformApi (documentId, fileName, documentType, verificationStatus, createdAt, updatedAt). The per-document verificationStatus collapses to PENDING / VERIFIED / FAILED (KYX lifecycle).

GET /v1/parties/kyx/{arkVerificationId}/documents — list document outcomes

Returns { arkVerificationId, data: [...] }. Each item carries a documentType mapped from the provider's KYX document type (DRIVERS_LICENCE, PASSPORT, NATIONAL_HEALTH_ID, ASIC_REGISTRATION, ABR_REGISTRATION).

GET /v1/parties/kyx/{arkVerificationId}/documents/{documentId} — not implemented

This route is a stub: it always returns 501 GEN101007 (NOT_IMPLEMENTED) — same code as the SOLE_TRADER KYX-initiate stub; both go through ArkExceptionFactory.notImplementedFrom.

GET /v1/parties/kyx/{arkVerificationId}/verification — retrieve verification data

Returns the provider's detailed KYXVerificationDataResponse, relayed verbatim. This is the only KYX route that requires a party context (bearer token plus an ACTIVE party in the partyid header).

---

Errors

Party-domain error codes use the PAR prefix.

HTTP	Code	When
400	GEN000000	Request body/params fail schema validation; or a document upload supplies neither identityDocument nor fileUpload; or missing required update fields
400	PAR000008	KYX address carries fields the provider cannot handle
400	PAR000011	Search supplied no usable parameters
400	PAR000012	Search supplied both individual and company parameters
400	PAR000013	Relationship request links a party to itself
400	PAR000003	KYX initiate entity type unsupported by the request mapper
403	AUT003001	Cross-tenant probe (different clientid) rejected by the access guard
404	PAR004001	Party not found, wrong entity type for relationships, or related party not found
409	PAR009004	Party entity type is TRUST/PARTNERSHIP (seeded but not wired)
422	PAR022001	Provider returned an unrecognised KYX verification status
500	PAR100002	Provider communication failure
501	GEN101007	SOLE_TRADER KYX initiate, and single-document GET stub (both via notImplementedFrom)