API Reference

Base URLs

Live keys are only issued after VeroID approves your account for live production verification, and return 403 on every endpoint until then. See Authentication.

All requests must include the X-API-Key header.

Verify Document

Verify an identity document by checking details with the document issuer or official record holder.

POST /v1/verify

Embedded document session

Developer accounts only. Creates a consent-first iframe session (typed fields, no SMS or biometrics). See Embedded document form for mounting the SDK and webhooks.

POST /v1/verify/embed-sessions

Optional prefill object: givenName, familyName, dateOfBirth (YYYY-MM-DD), middleName (driver's licence only), and gender (M, F, or X; passport only). Non-empty values hide the matching field in the iframe and are merged at submit (never returned to the browser or webhook). For givenName, familyName, and dateOfBirth, null or "" means not provided. For middleName, null or "" means the person has no middle name: hide the field and run the check without a middle name; omit the key to show the field. For gender on passport sessions, null or "" hides the field and runs the check without gender; omit the key to show the optional field. On other document types, gender in prefill is ignored. Invalid prefill returns 400 / INVALID_PREFILL with a field-specific message.

{
  "consentVersion": "1.0",
  "documentType": "drivers_licence",
  "allowedOrigins": ["https://app.example.com"],
  "prefill": {
    "givenName": "Jane",
    "middleName": null,
    "familyName": "Public",
    "dateOfBirth": "1985-06-20"
  }
}

Request Headers

Common Request Fields

Every request requires documentType, consentAttestedAt, and consentVersion, plus the document-specific fields - see Document Types for per-document schemas. Design consent flows using Consent & IVS obligations and official IDMatch guidance.

Response (POST /v1/verify)

The real-time verification result is returned in the response body. The status and match fields reflect the verification outcome and are only available here - they are not stored or retrievable via the GET endpoints.

{
  "success": true,
  "verificationId": "ver_abc123xyz",
  "documentType": "drivers_licence",
  "status": "success",
  "match": true,
  "responseCode": "Y",
  "message": "The details matched the document issuer's record.",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "environment": "live",
  "requestId": "req_xyz789"
}

Primary result codes are Y, N, D, and S. The status field maps those codes to success, failed, invalid_input (request failed validation before reaching the issuer), or error (system error). Field-level hints may appear on some no-match results. See Expanded Responses.

Result codes

test verification environment records

For integration testing against the real test verification hub (not the simulated sandbox), use the confirmed IVS/Fujitsu test records published on the Sandbox page. Each case includes the full request body and the expected responseCode: only records where both verification cycles matched the expected outcome are listed.

Requires a sk_test_* key and an account approved for the test verification hub. Send requests to https://test-api.veroid.com.au/v1/verify. sk_live_* keys only work on https://api.veroid.com.au.

Expanded Responses (field-level hints)

When the issuer supports expanded responses, VeroID may return an errors array with optional field-level hints on no-match results (responseCode N with status failed, or status invalid_input for validation failures). Hints are free-text messages that vary by issuer; not every no-match includes them. D responses do not include hints.

When hints appear

• status is failed with responseCode N and the issuer provides a hint
• status is invalid_input (validation failure before the issuer match)
• At most one hint entry is returned per request when present

Y (match) and D responses do not include errors. S (system error) responses typically do not either.

errors entry schema

Example - match (Y)

{
  "success": true,
  "verificationId": "ver_abc123xyz",
  "documentType": "drivers_licence",
  "status": "success",
  "match": true,
  "responseCode": "Y",
  "message": "The details matched the document issuer's record.",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "environment": "live",
  "requestId": "req_xyz789"
}

Example - no match with issuer hint (N)

{
  "success": true,
  "verificationId": "ver_abc123xyz",
  "documentType": "drivers_licence",
  "status": "failed",
  "match": false,
  "responseCode": "N",
  "message": "The details did not match the document issuer's record.",
  "errors": [
    { "source": "issuer", "field": "GivenName", "message": "Given name not matched" }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "environment": "live",
  "requestId": "req_xyz789"
}

Example - validation failure (invalid_input)

{
  "success": true,
  "verificationId": "ver_abc123xyz",
  "documentType": "drivers_licence",
  "status": "invalid_input",
  "match": false,
  "responseCode": "N",
  "message": "Licence Number must not exceed 10 characters",
  "errors": [
    { "source": "validation", "field": "LicenceNumber", "message": "Licence Number must not exceed 10 characters" }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "environment": "live",
  "requestId": "req_xyz789"
}

Example - could not complete (D)

{
  "success": true,
  "verificationId": "ver_abc123xyz",
  "documentType": "drivers_licence",
  "status": "failed",
  "match": false,
  "responseCode": "D",
  "message": "The check could not be completed. Please review the details and try again.",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "environment": "live",
  "requestId": "req_xyz789"
}

On the test endpoint, use confirmed IVS test records for predictable outcomes. Legacy in-memory family-name triggers (dvsmatch, dvsnomatch, dvsdata, dvssystem) apply only to local package tests, not test-api.veroid.com.au. See Test environment.

POST response fields

Verification response codes

These are the only four codes returned by the live verification hub (per the IVS interface specification):

GET Endpoint Status Values

The GET /v1/verify/:id and GET /v1/verify endpoints return a status field representing the processing state of the request - not the match outcome, which is only in the real-time POST response.

Get Verification

Retrieve the processing state of a previous verification. The match result (match, responseCode, errors) is not stored and will not appear here - it is only available in the real-time POST response. See IVS terms and conditions 12.5.

GET /v1/verify/:id

Response (GET /v1/verify/:id)

{
  "verificationId": "ver_abc123xyz",
  "documentType": "drivers_licence",
  "status": "completed",
  "environment": "live",
  "requestedAt": "2026-05-19T10:30:00.000Z",
  "completedAt": "2026-05-19T10:30:01.200Z"
}

If the verification encountered a system error, an error object is included:

{
  "verificationId": "ver_abc123xyz",
  "documentType": "drivers_licence",
  "status": "error",
  "environment": "live",
  "requestedAt": "2026-05-19T10:30:00.000Z",
  "completedAt": "2026-05-19T10:30:01.200Z",
  "error": {
    "code": "HUB_SYSTEM_ERROR",
    "message": "A system error occurred at the issuer or in the Hub"
  }
}

List Verifications

List your recent verifications.

GET /v1/verify

Query Parameters

Screening

Screen persons and organisations against sanctions, PEP, and optional adverse media. See Screening API for full documentation.

POST /v1/screening

Optional Idempotency-Key header (same rules as verify session create). List with GET /v1/screening?limit= and optional externalReference= (exact match, account-scoped).

Live screening is available after the developer onboarding fee is paid. Live verification approval is not required for screening endpoints.

Health Check

Check API status. No authentication required.

GET /health