Delete journey data with the API

To delete a journey session, send its instanceId to the /journey/state/delete endpoint. You can delete only finished journeys, which are journeys that completed or failed. The API rejects a request to delete a journey that’s still in progress. Use this endpoint when you need to remove a journey session before your normal data-retention period ends. Deletion is permanent, and you can’t undo it.

This request deletes the journey’s data from the GBG Go API service only. It doesn’t delete the journey session record, documents, or biometrics in the Investigation portal. To delete those, for example for a GDPR erasure request, use Delete journey session in the Investigation portal.

Before you begin

Make sure you have:

Access token: Your organisation’s customer access token, obtained in Step 1: Authenticate. Use the same token as for your other v2 calls. An end-user session token doesn’t work.
Delete access: Your API credentials need the DELETE:journey permission. If you get a 403 error, then ask your GBG account manager to enable it.
Instance ID: The instanceId returned by /journey/start when the journey started.

Choose the base URL for your region

Call the API in the region where the journey ran. A request for a journey that belongs to another organisation, or that isn’t available in the region you call, returns 404.

Region	Base URL
Europe	`https://eu.platform.go.gbgplc.com/v2/captain`
United States	`https://us.platform.go.gbgplc.com/v2/captain`
Australia	`https://au.platform.go.gbgplc.com/v2/captain`

The examples on this page use the Europe base URL. If your journeys run in another region, then replace eu with us or au.

Step 1: Check that the journey has finished

This step is optional. If you’re not sure whether the journey has finished, then fetch its state first.

cURL

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/state/fetch \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "your-instance-id"
  }'

For the status values in the response, see Step 5: Fetch journey state. If the journey is still running, then the delete request returns a 400 error. Wait for the journey to finish, then delete it.

Step 2: Delete the journey session

Send a POST request to /journey/state/delete with the instanceId in a JSON body. The endpoint uses the POST method, not the HTTP DELETE method.

cURL

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/v2/captain/journey/state/delete \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "your-instance-id"
  }'

Request headers

Header	Value
`Authorization`	`Bearer <access token>`
`Content-Type`	`application/json`

Request body fields

Field	Type	Required	Description
`instanceId`	string	Yes	The journey instance ID returned by `/journey/start`. It’s 16 to 64 characters long and contains only letters, numbers, underscores, and hyphens.

Handle the response

A 200 response means that GBG Go processed the deletion. In rare cases, some of the journey’s stored data can remain until the normal retention cleanup runs. Don’t treat a 200 as proof of erasure.

Success response

JSON

{
  "instanceId": "<instanceId>",
  "status": "deleted",
  "message": "Journey <instanceId> successfully deleted"
}

Field	Type	Description
`instanceId`	string	The instance ID of the deleted journey.
`status`	string	Always `deleted`.
`message`	string	A confirmation message that includes the instance ID.

Error responses

Each error returns an HTTP status and a GBG error code.

HTTP status	GBG code	When it happens	What to do
`400`	`4002`	The `instanceId` is missing, or the journey is still in progress.	Send a valid `instanceId`. If the journey is still running, then wait for it to finish.
`401`	`2001`	The access token is missing, expired, or invalid.	Get a new access token and retry.
`403`	`2002`	Your credentials don’t have delete access.	Ask your GBG account manager to enable delete access.
`404`	`1001`	The journey doesn’t exist, was already deleted, belongs to another organisation, or isn’t available in the region you call.	Check the `instanceId`, and check that you’re calling the right region.
`500`	`5001`	An unexpected error occurred.	Retry once. If the error repeats, then contact GBG support with the `instanceId` and the time of the call.
`503`	`5005`	The service is temporarily unavailable.	Retry, and wait longer between each attempt.

Every error uses the standard GBG error body:

JSON

{
  "errors": [
    {
      "code": "4002",
      "name": "MISSING_FIELD",
      "problem": "Only terminal journeys (completed or failed) can be deleted",
      "action": "Only terminal journeys (completed or failed) can be deleted. Check the journey status first.",
      "location": "Body"
    }
  ]
}

The errors array contains at least one error object, with these fields:

Field	Type	Required	Description
`code`	string	Yes	The four-digit GBG error code.
`name`	string	Yes	The name of the error.
`problem`	string	Yes	A description of the problem.
`action`	string	Yes	The action to take to fix the problem.
`location`	string	No	Where the problem is. One of `Path`, `Authorization`, `Header`, `Query String`, `Request`, `Body`, `Service`, or `Flow`.

What gets deleted

The delete request removes the journey’s stored state from the GBG Go journey service. The request deletes:

The journey’s workflow and execution state.
The data collected and produced during the journey that the journey service holds. This includes submitted inputs and module results.

After deletion, you can’t fetch, resume, or delete the journey through the v2 API. A later /journey/state/fetch or /journey/state/delete request for the same instanceId returns 404. The request doesn’t delete:

Journey session records, documents, and images in the Investigation portal.
Journey events that GBG Go already delivered to your organisation, such as webhooks or exports.
Any copy that you stored in your own systems.

To delete the journey session record, documents, and biometrics, use Delete journey session in the Investigation portal. Don’t rely on this request alone.

FAQ

Does deleting a journey session delete all customer data?

No. It deletes the journey’s data from the GBG Go API service only. To delete the journey session record, documents, and biometrics, use Delete journey session in the Investigation portal.

Can I delete a journey that's still running?

No. Wait for the journey to finish, then delete it. You can’t stop a running journey with POST /journey/terminate, because it accepts only journeys that completed or failed.

Can I undo a deletion?

No. Deletion is permanent.

Is it safe to retry a delete request?

Yes, for 500 and 503 errors. If a retry returns 404, then the earlier request most likely succeeded.

Can I delete several journeys in one request?

No. Send one request for each instanceId.

Why do I get a 404 error for a journey that I know exists?

Check that you’re calling the region where the journey ran. Also check that you’re using your own organisation’s credentials.

Who do I contact for help?

Contact your GBG account manager or GBG support. Include the instanceId, the region, and the time of the request in UTC.

Get Started

Platform

API-first integration

Hosted journey

Resources

Delete journey data with the API

Before you begin

Choose the base URL for your region

Step 1: Check that the journey has finished

Step 2: Delete the journey session

Request headers

Request body fields

Handle the response

Success response

Error responses

What gets deleted

FAQ

​Before you begin

​Choose the base URL for your region

​Step 1: Check that the journey has finished

​Step 2: Delete the journey session

​Request headers

​Request body fields

​Handle the response

​Success response

​Error responses

​What gets deleted

​FAQ

Before you begin

Choose the base URL for your region

Step 1: Check that the journey has finished

Step 2: Delete the journey session

Request headers

Request body fields

Handle the response

Success response

Error responses

What gets deleted

FAQ