SimpleKYC connector — endpoints
How to call the connector. The formal schema is the OpenAPI specification (KYX Check API,
openapi/source/connector/kyx/kyx.yml); this page covers the call contract and the values you
supply. Internal processing is in the architecture; caveats in the connector notes.
Authentication
All /v1/kyx/* endpoints require a bearer token (OAuth2 client-credentials JWT). Health endpoints are unauthenticated probes. (This is the Ark-facing auth; the connector's own auth to SimpleKYC is separate — see the architecture.)
| Method | Path | Purpose |
|---|---|---|
GET | /v1/kyx/search | Search for a business entity |
POST | /v1/kyx | Open a business verification |
GET | /v1/kyx/{arkVerificationId} | Check status |
POST | /v1/kyx/{arkVerificationId}/documents | Upload a supporting document |
GET | /v1/kyx/{arkVerificationId}/documents | List registry/document outcomes |
GET | /v1/kyx/{arkVerificationId}/verification | Full business report |
GET | /health · /health/readiness · /health/liveness | Probes (see architecture) |
arkVerificationId is the Ark verification id (UUID) returned by POST /v1/kyx as checkId.
GET /v1/kyx/search — business entity search
| Param | Required | Notes |
|---|---|---|
query | ✓ | business name, ABN, or ACN |
searchType | — | name (default) or number |
country | — | defaults to AU |
state | — | state/territory filter |
Returns BusinessSearchResponse — { matches: [{ entityName, businessNumber, companyNumber, entityType, status, matchScore, tradingNames }], totalResults }. registrationDate and state
are not populated from the search response.
POST /v1/kyx — open a verification
Body — InitiateKYXBusinessCheckRequest (provide at least one identifier):
| Field | Notes |
|---|---|
businessNumber | ABN |
companyNumber | ACN |
businessName | organisation name |
country | defaults to AU |
referenceId | optional external reference |
entityType | COMPANY, PARTNERSHIP, SOLE_TRADER, TRUST, … |
Creates a SimpleKYC application, stores the id mapping, and returns the initial KYXCheckResponse
({ checkId, vendorId, verificationStatus, dateCreated }). verificationStatus is normalised from
SimpleKYC (lifecycle).
GET /v1/kyx/{arkVerificationId} — status
Returns the current KYXCheckResponse, re-reading SimpleKYC status on each call. 404 PAR004006
if the id is unknown.
POST /v1/kyx/{arkVerificationId}/documents — upload a document
Uploads a supporting document (e.g. trust deed) to the SimpleKYC application. The request body is
a PartyDocumentCreationRequest whose fileUpload carries applicationId, base64 file (must
be a PDF), documentType (TRUST_DEED, TRUST_AMENDMENT, DRIVERS_LICENCE,
PARTNERSHIP_AGREEMENT), optional jurisdiction (country defaulting to AU, state), and
optional entity references (cn, bn, pcn, other, associatedEntityName). Returns the
refreshed KYXCheckResponse. A failed SimpleKYC upload returns 500 GEN100000; an unknown
arkVerificationId returns 404 PAR004006.
GET /v1/kyx/{arkVerificationId}/documents — registry/document outcomes
Returns GetKYXDocumentsResponse with two synthesised registry results derived from the SimpleKYC
report — an ASIC_REGISTRATION item (pass/fail on company-number status, with beneficial owners
and officeholders embedded) and an ABR_REGISTRATION item (ABN/GST). These are registry checks,
not records of uploaded files — see the connector notes.
GET /v1/kyx/{arkVerificationId}/verification — full business report
Returns KYXVerificationDataResponse: business overview, beneficial owners (ultimate + intermediate
with ≥ 25% ownership), officeholders, business/former names, and structured ASIC/ABR verification
results with raw-data snapshots. 404 PAR004006 if the id is unknown.
Errors
| HTTP | Code | When |
|---|---|---|
400 | GEN000000 | Request body/params fail schema validation |
401 | GEN001002 | Missing or invalid bearer token (enforced by AuthGuard) |
404 | PAR004006 | No verification mapping for arkVerificationId |
500 | GEN100000 | SimpleKYC document upload failed, or an unknown SimpleKYC status was returned |
500 | PAR100013 | KYX connector error (declared by the shared KYX OAS for connector failures; this connector currently raises only GEN100000 for its own server-side errors) |
The OpenAPI spec also documents additional codes the connector does not currently raise.