gofs:// format that you convert into a token and exchange for the image through a separate request. This guide covers that exchange.
The file object endpoint described in this guide is not yet part of the API reference. The behaviour described here is confirmed against the AU platform region.
What you need
Before you retrieve an image, make sure you have:- Access token: Obtained in Step 1: Authenticate. No separate credential is needed.
- Completed journey: A journey with a
Completedstatus, confirmed in Step 5: Fetch journey state. - Image references: The
gofs://values from the journey state response.
Where the image references live
In the journey state response, the references sit undercontext.subject:
The
biometrics array holds two selfie-related entries, a plain selfie and an encryptedSelfie. To retrieve an image, use the plain selfie entry. The encrypted entry is the raw biometric blob submitted during the journey and is not a viewable image.
Understand the gofs:// reference format
A reference looks like this:Reference
Format
Parse this string only to identify
orgId, which you need for the request URL. Otherwise, pass the reference through as a single opaque token.
Convert a reference into a request token
Convert the reference into a base64url token before you use it in a request. This is a standard, deterministic transformation:- Take the full
gofs://string, exactly as returned. - Base64-encode it.
- Make it URL-safe. Replace
+with-, and replace/with_. - Strip any trailing
=padding characters.
Retrieve the image
Send aGET request to the file object endpoint with the token. The following examples send the request. The Node.js, Python, Java, and PHP examples also decode the response into image bytes:
Request fields
The request URL uses the regional endpoint that matches your deployment. To find the endpoint for your region, refer to the API reference overview.
Response
The image is returned base64-encoded in the response body. Decode it to obtain the raw JPEG or PNG bytes.Handle single-sided and double-sided documents
Before you request the back-of-document image, check whetherside2Image was present in the journey state response:
- Present: The document is double-sided, such as a driver licence. Retrieve both
side1Imageandside2Image. - Absent: The document is single-sided, such as a passport. Retrieve
side1Imageonly, and skip the back-image request. Do not send the request with an empty or missing token.
side1Image, because there is no back side to capture. A driver licence produces both sides. Check for side2Image before you attempt to retrieve it.
Image retention and anonymisation
Image references reflect the evidence captured at the time the journey completed. They are not permanent. The underlying files are anonymised once the retention period configured for your organisation elapses. After that point, the reference no longer resolves to an image.Error handling
If the request fails, then the response uses the standard error envelope. For the full list of error codes, refer to Error handling.Sample response excerpt
The following excerpt shows thecontext.subject portion of a journey state response, with the image references in place. The orgId and instanceId values are illustrative.
JSON
selfie biometric entry and the document’s side1Image and side2Image fields. The encryptedSelfie entry, the anchorImage entry, and the classification detail are used elsewhere in the journey.