> ## 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.
# Run the account opening API sample app
> Run the banking account opening API sample app against your own journey, using the GBG Go Journey API v2.
In this tutorial, you'll run a working account opening application against your own GBG Go journey.
The source for this sample app is on GitHub:
* [go-sample-frontend](https://github.com/gbgplc/go-sample-frontend): the React front end, shared by all three sample apps.
* [go-sample-backend-java](https://github.com/gbgplc/go-sample-backend-java): the Java backend.
* [go-sample-backend-typescript](https://github.com/gbgplc/go-sample-backend-typescript): the TypeScript backend.
You need the front end and one backend. Both backends expose the same HTTP API, so the front end works with either.
## What this tutorial covers
By the end, you'll have an account opening application that:
* Starts a verification journey through the Go Journey API v2.
* Renders each screen from the journey's own configuration, rather than from hardcoded forms.
* Collects identity details, contact details, an address, a photo ID, and a selfie.
* Screens the applicant against PEPs and sanctions lists.
* Polls for the outcome and shows the decision, including a referral to manual review.
When a journey finishes, you can see it in the [Investigation](/docs/go-v2/platform/investigate/overview) portal.
This is the API sample app tutorial. It covers the API-first integration only, and does not cover the SDK or hosted journeys. For how the sample apps are built and what they share, see the [Sample applications overview](/docs/go-v2/tutorials/sample-apps-overview).
## Prerequisites
* Access to the Go dashboard, with permission to create and publish journeys.
* Licences for the modules this tutorial uses. Licences are assigned to your department by GBG, and an unlicensed module shows a warning icon in the Journey builder.
* An API client. See [Manage API clients](/docs/go-v2/platform/account-management/manage-api-clients) for how to create one and get your client ID and secret.
* Node.js v18 or higher, for the front end and the TypeScript backend.
* JDK 21 and Maven, only if you choose the Java backend.
* Git, to clone the sample repositories.
The modules this journey uses are Document Classification v2, Document Extraction v2, Document Authentication v2, Facematch Verification, Data Verification, PEPs and Sanctions Standard, GBG Trust EMEA, Address Verification (Global), Document Attachments, and Manual Review.
## Part 1: Build the journey
The application renders its screens from whatever your journey collects, so the journey comes first.
An account opening journey does more than confirm who someone is. It also screens them against sanctions and PEPs lists, and it gives a reviewer a way to resolve the cases that sit between accept and reject.
The finished journey looks like this. Eight modules run in sequence, then three evaluation nodes route the applicant to accept, reject, or a manual review that a person resolves.
In the Journey builder, add these modules in order:
| Module | What it does |
| - | - |
| Document Classification (Document Classification V2) | Identifies the document and confirms it is a type you accept |
| Document Extraction (Document Extraction V2) | Reads the data fields off the document |
| Document Authentication (Document Authentication V2) | Checks the document is genuine |
| Facematch Verification (Facematch Verification - NIST) | Compares the selfie against the document photo |
| Data Verification (UK: Single match all sources) | Matches the applicant's details against trusted data sources |
| PEPs and Sanctions (PEPs and Sanctions Standard) | Screens the applicant against politically exposed person and sanctions lists |
| GBG Trust (GBG Trust EMEA) | Returns a risk score for the applicant, drawn from the GBG Trust Network |
| Address Verification (Global) | Confirms the address is real and matches the applicant |
Select the **v2** variant of each document module, for example **Document Classification v2** rather than **Document Classification**. The v2 variants are built for this API.
For instructions, see [Configure modules](/docs/go-v2/platform/journey-builder/configure-module).
Address Verification takes the country from its own settings rather than from the applicant's address, so it needs setting before the journey runs.
1. Click the **Address Verification (Global)** module in the journey.
2. Click **Settings**.
3. In the **Country** field, enter the ISO3 code for the country you verify addresses in, for example `GBR`.
4. Click **Save all settings**.
ISO3 codes are the GO platform convention, so `GBR`, `FRA` or `DEU`. An ISO2 code such as `GB` is also accepted. For US addresses, use the dedicated US variant instead, which is certified for USPS DPV and CASS.
The module screens against whichever datasets its settings name. This tutorial uses Politically Exposed Persons only, so the evaluation has a single outcome to act on.
1. Click the **PEPs and Sanctions Standard** module in the journey.
2. Click **Settings**.
3. Click the **Datasets** field and select **Politically Exposed Persons**. Remove any other dataset, so it's the only one listed.
4. Click **Save all settings**.
You can screen against sanctions lists too by adding that dataset here. If you do, the module can return a match from either list, so revisit the PEPs and Sanctions conditions in your evaluation.
Add an **Evaluation** node after the modules and configure these three decisions. For how to add and configure one, see [Set up evaluation](/docs/go-v2/platform/journey-builder/set-up-evaluation).
| Decision | Classification | Match | Conditions |
| - | - | - | - |
| Reject | Negative | All Match | Document Extraction is Extraction Unsuccessful, Document Authentication is High Risk, Facematch Verification is Fail, and Document Classification is Document NOT Classified |
| Manual review | Neutral | Any Match | Data Verification is Partial Match, PEPs and Sanctions is MATCH, or Address Verification is Partially Verified |
| Accept | Positive | Any Match | Document Classification is Document Classified, Document Extraction is Extraction Successful, Document Authentication is Low Risk or Medium Risk, Facematch Verification is Success, Data Verification is Match, PEPs and Sanctions is NO MATCH, or Address Verification is Verified |
Set the classification on each decision as shown. The application reads it to choose a result screen, where `positive` renders an approval, `negative` a decline, and `neutral` a referral to manual review.
Give the Reject and Accept branches an **End of journey** node.
The Manual review branch does not end the journey. It hands the case to a person.
On that branch, add:
1. A **Document Attachments** module, so the reviewer has the captured document to look at.
2. A second **Evaluation** node with one decision, Manual review with classification Neutral and All Match, where Document Attachments is ATTACHED.
3. A **Manual Review** module on that branch, configured as a two-button review.
The Manual Review module pauses the journey until a reviewer acts.
Add a final **Evaluation** node after the Manual Review module, to turn the reviewer's answer into a decision:
| Decision | Classification | Match | Condition |
| - | - | - | - |
| Reject | Negative | All Match | Manual Review is Deny |
| Manual review | Neutral | All Match | Manual Review is Timeout |
| Accept | Positive | All Match | Manual Review is Accept |
Give each branch an **End of journey** node.
A Timeout stays neutral because nobody decided. The applicant sees the same referral screen as before.
Click **Publish to Preview**. You'll see the confirmation message *Delivery deployed successfully*.
Use Preview while you build and test. Publish to Production when you're ready for real applicants. The application works the same against either, and only the resource ID changes.
Go to **Dashboard** in the Journey builder and copy the **Resource ID** and **Version number**.
You'll combine them as `@`, for example:
```
f3d875bc2ebff66f557fb177646f4c80e453d8d064b92a53fd1079edded1ea91@2lhovl4z
```
Pin the exact version rather than using `@latest`. Every republish creates a new version, and a pinned application keeps running the version you tested until you change it deliberately.
## Part 2: Set up the backend
Clone the backend in the language you prefer. Both expose the same HTTP API, so the front end works with either.
```bash theme={null}
git clone https://github.com/gbgplc/go-sample-backend-java.git
cd go-sample-backend-java
```
`.env.local` is listed in `.gitignore`, so Git doesn't track it. Never commit your client secret, and never put it in `application-*.yml`.
Create a file named `.env.local` in the repository root:
```bash theme={null}
GBG_CLIENT_ID=your-client-id
GBG_CLIENT_SECRET=your-client-secret
```
Open `src/main/resources/application-northbank.yml` and set your journey:
```yaml theme={null}
app:
resource-id: your-resource-id@your-version
```
Start the service in live mode:
```bash theme={null}
./run.sh northbank live
```
It listens on `http://localhost:8081`. The script finds JDK 21, loads `.env.local`, and starts the right profile.
```bash theme={null}
git clone https://github.com/gbgplc/go-sample-backend-typescript.git
cd go-sample-backend-typescript
npm install
```
`.env.local` is listed in `.gitignore`, so Git doesn't track it. Never commit your client secret, and never put it in a market config.
Create a file named `.env.local` in the repository root:
```bash theme={null}
GBG_CLIENT_ID=your-client-id
GBG_CLIENT_SECRET=your-client-secret
```
Open `lib/config/markets/northbank.ts` and set your journey:
```typescript theme={null}
resourceId: 'your-resource-id@your-version',
```
Start the service in live mode:
```bash theme={null}
npm run dev:northbank:live
```
It listens on `http://localhost:8081`.
Both backends also have a mock mode that needs no credentials, which is useful for working on the front end alone. The `live` command is what switches them to your real journey.
### Set your region
The samples default to the EU platform. If your tenant was provisioned elsewhere, then change the base URL and the region together:
Change both values. Authentication succeeds regardless of region, so a mismatch shows up later as journey calls failing against the wrong host.
In `application-northbank.yml`:
```yaml theme={null}
go:
region: us
base-url: https://us.platform.go.gbgplc.com/v2/captain/
```
In `lib/config/markets/northbank.ts`:
```typescript theme={null}
go: {
region: 'us',
baseUrl: 'https://us.platform.go.gbgplc.com/v2/captain/',
},
```
## Part 3: Set up the front end
The front end is one repository holding three applications. This tutorial uses the banking one.
```bash theme={null}
git clone https://github.com/gbgplc/go-sample-frontend.git
cd go-sample-frontend
npm install
```
Create `apps/northbank/.env.local`:
```bash theme={null}
NEXT_PUBLIC_ONBOARDING_TRANSPORT=rest
NEXT_PUBLIC_API_BASE_URL=http://localhost:8081
```
`NEXT_PUBLIC_*` values are compiled into the browser bundle. Never put credentials here. They belong in the backend's `.env.local`.
Start the front end:
```bash theme={null}
npm run dev:northbank
```
Open `http://localhost:3000`. With the backend already running, you'll land on the first screen of your own journey.
If you see the **About you** screen, the whole chain is working, from the browser through the front end and backend to GBG Go.
To understand the request flow the app uses, and how it renders screens from your journey, see [How the applications are built](/docs/go-v2/tutorials/sample-apps-overview#how-the-applications-are-built).
## Troubleshooting
On this journey the document element sits under an optional parent, so its refs never appear in `outstanding`. The sample marks that screen `always-collect` in the Java config, or `alwaysCollect` in TypeScript, so it renders from `collects` regardless.
If you build your own screen plan and the document screen never appears, this is why.
The screen plan doesn't recognise something the journey collects, so the app falls back to a plain form rather than stalling.
This usually means the journey changed after the plan was written. Check the backend log for `No screen mapped for outstanding elements`, which names the unmapped elements, then add them to the screen plan.
The journey's required fields changed under the same resource ID. A republish can add required elements, so an address that needed three components can come back needing six, and a screen plan written against the old shape submits an incomplete element.
Re-read `collects` after every republish rather than assuming the shape holds.
The backend keeps sessions in memory, so restarting it invalidates every session in progress. Start a new journey.
For the same reason, the samples run one journey per browser tab. The session ID lives in `sessionStorage`, so reloading resumes the journey, but a new tab starts a fresh one.
The region is mismatched. The token endpoint is global, so authentication works regardless, but journey calls go to a regional host. Check that `region` and `base-url` name the same region.
A module that errors is different from one that declines, because nothing was decided about the customer.
Open the journey in the [Investigation](/docs/go-v2/platform/investigate/overview) portal and look at the failing step. It carries an error code, a problem description, a suggested action, and a correlation ID. Quote the correlation ID when contacting support, because it identifies the exact execution.
## Next steps
See the journeys you ran, module by module, in the Investigation portal.
Change what each module reports, and how your evaluation turns those into decisions.
Move from Preview to Production when you're ready for real customers.
The full Journey API v2 reference.