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

# Delete journey data with the API

> Permanently delete a finished journey session with the /journey/state/delete endpoint.

To delete a journey session, send its `instanceId` to the [`/journey/state/delete`](https://docs.go.gbgplc.com/docs/go-v2/api-reference/endpoint/delete-journey-state) 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.

> [!WARNING]
>
> 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](https://docs.go.gbgplc.com/docs/go-v2/platform/investigate/delete-journey-session.md) in the Investigation portal.

## Before you begin

Make sure you have:

* **Access token**: Your organisation's customer access token, obtained in [Step 1: Authenticate](https://docs.go.gbgplc.com/docs/go-v2/developer-integration/execute-customer-journeys/authenticate.md). 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`](https://docs.go.gbgplc.com/docs/go-v2/api-reference/endpoint/start-journey) 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.

```bash cURL theme={null}
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](https://docs.go.gbgplc.com/docs/go-v2/developer-integration/execute-customer-journeys/fetch-journey-state-step.md).

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.

```bash cURL theme={null}
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 JSON theme={null}
{
  "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 JSON theme={null}
{
  "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](https://docs.go.gbgplc.com/docs/go-v2/platform/investigate/delete-journey-session.md) in the Investigation portal. Don't rely on this request alone.

## FAQ

> [accordion] 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](https://docs.go.gbgplc.com/docs/go-v2/platform/investigate/delete-journey-session.md) in the Investigation portal.

> [accordion] 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.

> [accordion] Can I undo a deletion?
>
> No. Deletion is permanent.

> [accordion] 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.

> [accordion] Can I delete several journeys in one request?
>
> No. Send one request for each `instanceId`.

> [accordion] 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.

> [accordion] 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.