Skip to main content
When a journey completes, the journey state response contains references to the images captured during the journey: the customer’s selfie, and the front and back of their identity document. These references do not contain the image itself. They are pointers in the 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 Completed status, 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 under context.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
The format is colon-separated, not slash-separated. It has four parts:
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:
  1. Take the full gofs:// string, exactly as returned.
  2. Base64-encode it.
  3. Make it URL-safe. Replace + with -, and replace / with _.
  4. Strip any trailing = padding characters.
The following examples perform this conversion:
Any standard library base64 function produces the same result. This is not a GBG-specific encoding, it is a URL-safe variant of standard base64.

Retrieve the image

Send a GET 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 whether side2Image was present in the journey state response:
  • Present: The document is double-sided, such as a driver licence. Retrieve both side1Image and side2Image.
  • Absent: The document is single-sided, such as a passport. Retrieve side1Image only, and skip the back-image request. Do not send the request with an empty or missing token.
A passport only ever produces 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.
If you need to retain these images for your own compliance records, then retrieve and store them promptly after the journey completes. Retention is configured per account rather than fixed across the platform, so confirm your organisation’s retention window with your GBG account team.

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 the context.subject portion of a journey state response, with the image references in place. The orgId and instanceId values are illustrative.
JSON
To retrieve images, you need only the 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.