Skip to Content
VeroID

Document extract

Read document photos with hosted Australian data processing, then reuse the fields for a later check with the document issuer or official record holder.

POST /v1/verify/document-extract accepts a document image (and a second image when the layout requires it). The response includes per-field values, confidence hints where available, non-blocking capture flags, and a verifyRequest object you can send to POST /v1/verify after you collect consent. This endpoint does not call the issuer.

Image object shape

Both documentImage and documentBackImage use the same object:

  • contentType: image/jpeg or image/png (case insensitive)
  • base64: standard base64 of the image bytes. After decoding, each image may be at most 5,000,000 bytes (application validation).

Request body size

Two limits apply to POST /v1/verify/document-extract (and any large JSON POST to the public API):

  1. HTTP entry (about 6 MiB total body). The full JSON request, including base64 strings and field names, must stay under 6,291,456 bytes (6,291,456 bytes). If the body is larger, the edge returns 413 Request Entity Too Large before VeroID parses the JSON. Base64 adds roughly 33% size, so two large photos in one request exceed this limit easily.
  2. Per image (after decode). Each documentImage or documentBackImage may decode to at most 5,000,000 bytes. Larger decoded bytes return 400 IMAGE_TOO_LARGE from the application.

For a driver licence with front and back in one request, aim for roughly 2 MB decoded per side so the base64 JSON stays under the entry limit (about 2.7 MB base64 per side, plus JSON overhead). Practical guidance: resize photos to about 1600 px on the long edge, JPEG quality about 80, typically under 1 MB each before encoding.

POST /v1/verify sends field values only (no images) and is not subject to photo size limits.

documentBackImage by documentType

Omit documentBackImage when the table says Not used. Send it when the table says Required or when you have a second page for Optional types. If a type requires a back image and you send only documentImage, the API returns 400 with DOCUMENT_BACK_REQUIRED.

documentTypedocumentBackImageNotesFields in verifyRequest when found
drivers_licenceRequiredCard number is on the back for all states and territories.givenName, familyName, middleName, dateOfBirth, licenceNumber, stateOfIssue, cardNumber
passportNot usedData page with MRZ.givenName, familyName, dateOfBirth, passportNumber, gender
medicareNot usedFront of Medicare card.fullName, fullName2, fullName3, fullName4, dateOfBirth, medicareNumber, individualReferenceNumber, cardColour, expiryDate
visaOptionalVisa grant notice or visa label; MRZ on label when present.givenName, familyName, dateOfBirth, passportNumber, countryOfIssue
birth_certificateOptionalScan the certificate page that shows names, DOB, and registration details.givenName, familyName, dateOfBirth, certificateNumber, registrationDate, registrationNumber, registrationState, registrationYear
citizenshipNot usedCertificate of Australian citizenship.givenName, familyName, dateOfBirth, stockNumber, acquisitionDate
immicardNot usedImmiCard front.givenName, familyName, dateOfBirth, immiCardNumber
marriage_certificateOptionalSecond page if party names or registration block continues.givenName, familyName, givenName2, familyName2, dateOfMarriage, certificateNumber, registrationDate, registrationNumber, registrationState, registrationYear
change_of_name_certificateOptionalInclude page with previous and new name details if split across pages.givenName, familyName, dateOfBirth, oldGivenName, oldFamilyName, certificateNumber, registrationDate, registrationNumber, registrationState, registrationYear
death_certificateOptionalPage showing registration details for the registering state.givenName, familyName, dateOfDeath, certificateNumber, registrationDate, registrationNumber, registrationState
centrelinkNot usedConcession card front.name, customerReferenceNumber, dateOfBirth, cardExpiry, cardType
asic_msicNot usedASIC or MSIC card front.nameOnCard, dateOfBirth, cardNumber, cardExpiry, cardType

Only drivers_licence treats a missing documentBackImage as an error. Other types accept a single front image; optional second images improve extraction when details continue on another page.

Request examples

Passport (front only)

POST /v1/verify/document-extract
Content-Type: application/json
X-API-Key: sk_test_...

{
  "documentType": "passport",
  "documentImage": {
    "contentType": "image/jpeg",
    "base64": "..."
  }
}

Driver licence (front and back required)

POST /v1/verify/document-extract
Content-Type: application/json
X-API-Key: sk_test_...

{
  "documentType": "drivers_licence",
  "documentImage": {
    "contentType": "image/jpeg",
    "base64": "..."
  },
  "documentBackImage": {
    "contentType": "image/jpeg",
    "base64": "..."
  }
}

Response

{
  "id": "vdx_…",
  "documentType": "drivers_licence",
  "fields": { "cardNumber": { "value": "…", "confidence": "high" } },
  "extractionFlags": [],
  "captureFlags": [],
  "verifyRequest": { "documentType": "drivers_licence", "cardNumber": "…" },
  "images": {
    "document": { "retainedUntil": "…", "downloadPath": "…" },
    "documentBack": { "retainedUntil": "…", "downloadPath": "…" }
  },
  "createdAt": "2026-11-09T12:00:00.000Z"
}

Add consentAttestedAt and consentVersion to verifyRequest before you call POST /v1/verify. Review captureFlags and extractionFlags in your own rules; they never block the API response.

Error responses (document extract)

Before the application (large HTTP body)

These responses are returned by the public API entry. They are not the usual VeroID JSON error body with a code field.

Edge HTTP errors
HTTPcodeMeaning
413Not applicableRequest Entity Too Large. The entire HTTP request body exceeded 6,291,456 bytes (6291456 bytes). Common on document extract when two base64-encoded photos make the JSON too large. Resize images before encoding. This response does not include VeroID error codes such as IMAGE_TOO_LARGE.

POST /v1/verify/document-extract

Document extract POST errors
HTTPcodeMeaning
400DOCUMENT_BACK_REQUIREDdocumentBackImage was omitted but is required for this documentType (currently only drivers_licence).
400INVALID_IMAGE_FORMATdocumentImage or documentBackImage contentType is not image/jpeg or image/png.
400INVALID_IMAGE_ENCODINGbase64 could not be decoded for documentImage or documentBackImage.
400INVALID_IMAGE_EMPTYDecoded image bytes are empty.
400IMAGE_TOO_LARGEDecoded image exceeds 5,000,000 bytes (applies to each image).
422UNSUPPORTED_DOCUMENT_TYPEdocumentType is not one of the supported extract types.
422DOCUMENT_OCR_FAILEDText could not be read from the image (after format checks).
400Not applicableJSON body failed schema validation (missing documentType, documentImage, contentType, or base64). Response uses the standard validation error shape from the framework without a business code field.

Successful responses use 200. Business errors include a code field via publicErrorPayload.

GET /v1/verify/document-extract/:id/captures/:slot

slot must be document or document_back (underscore, not a hyphen).

Document extract capture download errors
HTTPcodeMeaning
400INVALID_CAPTURE_SLOTPath slot must be document or document_back.
404NOT_FOUNDNo extract with this id for your account.
404NOT_AVAILABLEThis slot was never stored (for example no back image on a passport extract).
410EXPIREDImages are only retained 24 hours after upload.

Shared verify API errors

The same authentication and account gates apply to document extract, POST /v1/verify, and other verify routes. Middleware responses use error and message; many do not include a code field.

Shared verify middleware errors
HTTPcodeMeaning
401Not applicableMissing or invalid X-API-Key. Postman users: select the Sandbox or Production environment and set apiKey. An empty apiKey or No Environment selected returns Missing API key.
403WRONG_API_ENDPOINTAPI key type does not match the API base URL (test vs live).
403Not applicableAccount cannot use verify APIs yet (developer access, test hub, live approval, privacy act, or hub phase). Message text describes the required dashboard step.
402Not applicableLive verify requires sufficient credits or an active invoiced account (POST /v1/verify only).
404Not applicableCustomer record not found for the API key.

POST /v1/verify and GET /v1/verify/:id

Document extract does not call the issuer. These endpoints share the middleware above. Additional HTTP errors from POST /v1/verify:

POST verify route errors
HTTPcodeMeaning
403SANDBOX_KEY_DEPRECATEDDeprecated sandbox key type.
403WRONG_API_ENDPOINTCustomer hub phase does not match this API deployment.
429DOCUMENT_COOLDOWNSame document submitted again too soon; see Retry-After header.
503HUB_NOT_CONFIGUREDVerification hub is not configured for this deployment (public alias for DVS_NOT_CONFIGURED).
400Not applicableRequest body failed ValidationRequestSchema or consent field checks (documentType, fields, consentAttestedAt, consentVersion).

A valid verification request usually returns 200 with issuer outcome fields even when the match fails (status: failed). See Errors for result handling.

GET /v1/verify/:id

GET verification by id errors
HTTPcodeMeaning
404Not applicableverificationId not found for your account.

Accuracy

Passport MRZ fields are the most reliable. When the MRZ cannot be read, the service may still return labelled visual-zone fields under VISUAL_ZONE_FALLBACK alongside MRZ_NOT_FOUND. Date values in verifyRequest are normalised to YYYY-MM-DD where possible (Medicare green card expiry uses YYYY-MM).

Cards with fixed layouts (Medicare, ImmiCard, concession cards) are moderate. Registry-issued certificates vary by state; you may need a second page image and manual review when extractionFlags includes BDM_LAYOUT_VARIANT or FIELD_MISSING.

Retrieving uploaded images

For 24 hours after upload, call GET /v1/verify/document-extract/:id/captures/document or …/captures/document_back with the same API key.

Test environment

Use a sk_test_* key on test-api.veroid.com.au. Pair extracted fields with confirmed IVS test records on the Test Environment page before you call POST /v1/verify. Import the Postman collection for a pre-built driver licence extract request with front and back placeholders.

Credits

Document extract is free. It does not consume verification credits on test or live API keys.