> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to retrieve KYC images from GBG Go

> Convert the image references returned in the journey state response into a token and exchange it for the captured selfie and document images.

When a journey completes, the [journey state response](https://docs.go.gbgplc.com/docs/go-v2/developer-integration/execute-customer-journeys/fetch-journey-state-step.md) 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.

> [!NOTE]
>
> The file object endpoint described in this guide is not yet part of the [API reference](https://docs.go.gbgplc.com/docs/go-v2/api-reference/overview.md). 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](https://docs.go.gbgplc.com/docs/go-v2/developer-integration/execute-customer-journeys/authenticate.md). No separate credential is needed.
* **Completed journey**: A journey with a `Completed` status, confirmed in [Step 5: Fetch journey state](https://docs.go.gbgplc.com/docs/go-v2/developer-integration/execute-customer-journeys/fetch-journey-state-step.md).
* **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`:

| Image | Location | Present when |
| - | - | - |
| Selfie | `context.subject.biometrics[]`, entry where `type` is `selfie` | Always |
| Encrypted selfie | `context.subject.biometrics[]`, entry where `type` is `encryptedSelfie` | Always, but not usually needed |
| Document, front | `context.subject.documents[0].side1Image` | Always |
| Document, back | `context.subject.documents[0].side2Image` | Only for double-sided documents, such as driver licences |

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:

```text Reference theme={null}
gofs://au:f087c30a-ec97-43d2-a82a-57423c01b3f5:UMtwjlP_QL2Ah63ksvCrxq:GBGGO-d5d0113209fa6fe2ac6f8aac758bf6eb_757f75ee-2b41-46ae-ab03-c91524028aad_White_jpeg_Camera
```

The format is colon-separated, not slash-separated. It has four parts:

```text Format theme={null}
gofs://<region>:<orgId>:<instanceId>:<filename>
```

| Part | Description |
| - | - |
| `region` | The regional deployment the file lives in, such as `au`. |
| `orgId` | Your organisation's identifier on the **GBG GO platform**. |
| `instanceId` | The journey instance the file belongs to. This matches the top-level `instanceId` in the journey state response. |
| `filename` | The underlying file name. |

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:

```javascript Node.js theme={null}
const token = Buffer.from(gofsReference)
  .toString('base64')
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
  .replace(/=+$/, '');
```

```python Python theme={null}
import base64

token = base64.urlsafe_b64encode(gofs_reference.encode()).decode().rstrip('=')
```

```java Java theme={null}
String token = Base64.getUrlEncoder()
    .withoutPadding()
    .encodeToString(gofsReference.getBytes(StandardCharsets.UTF_8));
```

```php PHP theme={null}
<?php
$token = rtrim(strtr(base64_encode($gofsReference), '+/', '-_'), '=');
```

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:

```bash cURL theme={null}
curl --request GET \
  --url https://eu.platform.go.gbgplc.com/v2/captain/files/your_org_id/object/your_token \
  --header 'Authorization: Bearer your_access_token'
```

```javascript Node.js theme={null}
const response = await fetch(
  `https://eu.platform.go.gbgplc.com/v2/captain/files/${orgId}/object/${token}`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const base64Image = await response.text();
const imageBytes = Buffer.from(base64Image, 'base64');
```

```python Python theme={null}
response = requests.get(
    f'https://eu.platform.go.gbgplc.com/v2/captain/files/{org_id}/object/{token}',
    headers={'Authorization': f'Bearer {access_token}'}
)

image_bytes = base64.b64decode(response.text)
```

```java Java theme={null}
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://eu.platform.go.gbgplc.com/v2/captain/files/"
        + orgId + "/object/" + token))
    .header("Authorization", "Bearer " + accessToken)
    .GET()
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

byte[] imageBytes = Base64.getDecoder().decode(response.body());
```

```php PHP theme={null}
<?php
$ch = curl_init("https://eu.platform.go.gbgplc.com/v2/captain/files/{$orgId}/object/{$token}");

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $accessToken]
]);

$imageBytes = base64_decode(curl_exec($ch));
curl_close($ch);
```

### Request fields

| Field | Required | Description |
| - | - | - |
| `orgId` | Yes | Your organisation identifier, taken from the `gofs://` reference. Use it exactly as it appears there. |
| `token` | Yes | The base64url token derived from the `gofs://` reference. |
| `Authorization` | Yes | The bearer token issued when you authenticated. |

The request URL uses the regional endpoint that matches your deployment. To find the endpoint for your region, refer to the [API reference overview](https://docs.go.gbgplc.com/docs/go-v2/api-reference/overview.md).

### 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.

> [!TIP]
>
> 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](https://docs.go.gbgplc.com/docs/go-v2/developer-integration/error-handling.md).

| Status | Likely cause |
| - | - |
| `401 Unauthorized` | The bearer token is missing, expired, or malformed. |
| `404 Not Found` | The token is malformed, the `orgId` is incorrect, or the image is already anonymised. |
| `400 Bad Request` | The token is not valid base64url, or it was not derived from a complete `gofs://` reference. |

## 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 JSON expandable theme={null}
{
  "subject": {
    "biometrics": [
      {
        "type": "encryptedSelfie",
        "selfieImageEncryption": true,
        "selfieImage": "gofs://au:{orgId}:{instanceId}:<hash>-selfieImage.biometric.bin"
      },
      {
        "type": "selfie",
        "selfieImageEncryption": false,
        "selfieImage": "gofs://au:{orgId}:{instanceId}:GBGGO-<hash>_<uuid>_White_jpeg_Camera"
      },
      {
        "type": "anchorImage",
        "anchorImage": "gofs://au:{orgId}:{instanceId}:GBGGO-<hash>_<uuid>_White_jpeg_Camera"
      }
    ],
    "documents": [
      {
        "type": "primary",
        "side1Image": "gofs://au:{orgId}:{instanceId}:<hash>-side1Image.document.jpg",
        "side2Image": "gofs://au:{orgId}:{instanceId}:<hash>-side2Image.document.jpg",
        "classification": {
          "countryCode": "AUS",
          "isDoubleSided": true,
          "type": "Drivers License"
        }
      }
    ]
  }
}
```

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.
