GreenID 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, the values you must supply, and examples. Internal processing of each endpoint is in the architecture; known gaps and caveats are in the connector notes.

Authentication

All /v1/kyx/* endpoints require a bearer token (OAuth2 client-credentials JWT). Health endpoints are unauthenticated infrastructure probes.

Method	Path	Auth	Purpose
`POST`	`/v1/kyx`	✓	Initiate a verification
`GET`	`/v1/kyx/{arkVerificationId}`	✓	Get verification status
`POST`	`/v1/kyx/{arkVerificationId}/documents`	✓	Submit an identity document
`GET`	`/v1/kyx/{arkVerificationId}/documents`	✓	List document outcomes
`GET`	`/health` · `/health/readiness` · `/health/liveness`	—	Probes (see architecture)

arkVerificationId is the Ark-side verification id (UUID) returned by POST /v1/kyx as checkId.

`POST /v1/kyx` — initiate a verification

Registers a new GreenID verification session for a person and returns the Ark verification handle.

Body — InitiateKYXCheckRequest:

Field	Required	Notes
`name.firstName`	✓
`name.lastName`	✓
`name.middleNames`	✓	array of strings (may be empty)
`name.prefix`	✓	one of `Mx`, `Mr`, `Mrs`, `Master`, `Miss`, `Ms`, `Prof`
`email`	✓
`dateOfBirth`	✓	`YYYY-MM-DD`
`address`	✓	`CommonPAFAddress` (Australia Post PAF format; `dpid` required)

// Request
{
  "name": { "firstName": "Jane", "lastName": "Citizen", "middleNames": ["Mary"], "prefix": "Ms" },
  "email": "jane@example.com",
  "dateOfBirth": "1990-04-12",
  "address": { "dpid": "12345678", "addressLine": "1 George St", "streetName": "George", "streetType": "St", "localityName": "Sydney", "postcode": "2000", "state": "NSW" },
}

Response — KYXCheckResponse:

{
  "checkId": "8e962b2d-d236-cbd1-9e90-ff9c84b28806", // Ark verification id (use as arkVerificationId)
  "vendorId": "43b8a730-20b3-42ef-946f-be3b1415a5ee", // GreenID verification id
  "verificationStatus": "IN_PROGRESS",
  "dateCreated": "2026-05-24T03:21:00.000Z",
  "dateVerified": null,
}

verificationStatus values and how they map from GreenID are in lifecycle.

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

Returns the current KYXCheckResponse (same shape as above). The connector re-reads the live status from GreenID on every call.

404 (PAR004006) if no verification mapping exists for the id.

`POST /v1/kyx/{arkVerificationId}/documents` — submit an identity document

Submits one identity document into the in-progress verification. The document is not stored by the connector; it is forwarded to GreenID. Returns the updated KYXCheckResponse.

Body — PartyDocumentCreationRequest with an identityDocument (IdentityDocumentObject):

Field	Required	Notes
`type`	✓	`DRIVERS_LICENCE`, `PASSPORT`, or `NATIONAL_HEALTH_ID`
`country`	✓	ISO-3166 alpha-3 (e.g. `AUS`) — see the connector notes
`region`	for licences	local abbreviation, e.g. `VIC` (selects the state DVS source)
`extraData[]`	in code	key/value pairs carrying the document fields (below). Optional per the OAS schema (only `type` + `country` are required), but the connector's per-type mapping needs the listed keys to submit a usable document.

The connector reads these extraData keys (kvpKey / kvpValue) per document type:

Document	`extraData` keys it reads
`DRIVERS_LICENCE`	`DOCUMENT_NUMBER`, `CARD_NUMBER`, `GIVEN_NAME`, `MIDDLE_NAME` (optional), `SURNAME`, `DATE_OF_BIRTH`, `CONSENT`
`PASSPORT`	`DOCUMENT_NUMBER`, `GIVEN_NAME`, `MIDDLE_NAME` (optional), `SURNAME`, `DATE_OF_BIRTH`, `CONSENT`
`NATIONAL_HEALTH_ID`	`DOCUMENT_NUMBER`, `DOCUMENT_REFERENCE_NUMBER`, `DOCUMENT_EXPIRY`, `NAME_ON_DOCUMENT`, `NAME_ON_DOCUMENT_2`, `NAME_ON_DOCUMENT_3`, `NAME_ON_DOCUMENT_4`, `DOCUMENT_COLOUR`, `DATE_OF_BIRTH`, `CONSENT`

CONSENT is a boolean-style flag: any non-empty value means consent given.

// Request — a Victorian driver's licence
{
  "identityDocument": {
    "type": "DRIVERS_LICENCE",
    "country": "AUS",
    "region": "VIC",
    "extraData": [
      { "kvpKey": "DOCUMENT_NUMBER", "kvpValue": "0123456789" },
      { "kvpKey": "CARD_NUMBER", "kvpValue": "ABC123" },
      { "kvpKey": "GIVEN_NAME", "kvpValue": "Jane" },
      { "kvpKey": "SURNAME", "kvpValue": "Citizen" },
      { "kvpKey": "DATE_OF_BIRTH", "kvpValue": "1990-04-12" },
      { "kvpKey": "CONSENT", "kvpValue": "true" },
    ],
  },
}

Documents can only be submitted while the verification is IN_PROGRESS and the target source is available — otherwise the call is rejected (422 PAR022001 / 500 PAR100013; see the architecture).

Preparing Medicare (`NATIONAL_HEALTH_ID`) payloads

DOCUMENT_COLOUR is typically G, B, or Y.
Green cards typically use MM/YYYY expiry formatting; other colours typically use DD/MM/YY.
The NAME_ON_DOCUMENT* lines should match the text printed on the Medicare card.

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

Returns GetKYXDocumentsResponse — one entry per supported document source GreenID has seen for the verification. Each entry carries the document type, the raw provider status, a normalised status category, an optional reason code, field-level check details, and provider messages. The response is derived live from GreenID, not from a stored document table.

{
  "arkVerificationId": "8e962b2d-d236-cbd1-9e90-ff9c84b28806",
  "data": [
    {
      "documentType": "DRIVERS_LICENCE",
      "verificationStatus": "VERIFIED",
      "verificationStatusCategory": "VERIFIED",
      "verificationReasonCode": "NC_DVS_D",
      "verificationDetails": {
        "checks": [
          /* provider field results */
        ],
      },
      "messages": ["Name does not match."],
    },
  ],
}

The provider-state → verificationStatusCategory mapping is in lifecycle.

404 (PAR004006) if no verification mapping exists for the id.

Errors

HTTP	Code	When
`400`	`GEN000000`	Request body fails schema validation, or the document is not a valid identity document
`401`	`GEN001002`	Missing or invalid bearer token (enforced by `AuthGuard`)
`404`	`PAR004006`	No verification mapping for `arkVerificationId`
`422`	`PAR022001`	Document submitted when the verification is not `IN_PROGRESS`
`500`	`PAR100013`	KYX connector error — GreenID call failed, or a required source is missing/unavailable

The OpenAPI spec also documents additional status codes (e.g. 403, 409, 412, 429) that the connector does not currently raise — see the connector notes.

Authentication​

POST /v1/kyx — initiate a verification​

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

POST /v1/kyx/{arkVerificationId}/documents — submit an identity document​

Preparing Medicare (NATIONAL_HEALTH_ID) payloads​

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

Errors​