# Get all external web links

`GET /api/configuration/externalweblinks`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`), Consumer (`CONSUMER`) (any one of these products, not all)
- **Features:** Online Bookings (`ONLINEBOOK`), Online Joining (`ONLINEJOIN`), Front of House Generic Access (`FOHGENERIC`) (any one of these features, not all)

HTML version: [Get all external web links](https://support.gladstonesoftware.cloud/reference/configuration/get-all-external-web-links)

## Overview

Lists every external web link the operator has configured. An external web link is a URL surfaced in the operator's consumer-facing app — typically a tile or menu item pointing at their own website, a partner site or a booking page — together with the image, target behaviour and category that control how it is presented.

**Inactive links are returned.** Every link is returned: there is no filter parameter, no guaranteed order, no paging, and the `status` field is not used to exclude anything. If you render this list straight into a UI you will show links the operator has switched off. Filter on `status` yourself, and remember it is nullable, so decide deliberately what a `null` status should mean for you.

Each link carries a `linkTypeId` rather than a type name. Fetch [the link types list](get-all-external-web-link-types.md) as well and join on it locally; both ids are tenant-specific and neither is safe to hard-code.

When no links are configured you get `200` with an empty array `[]`.

## Endpoint

`GET {base_url}/api/configuration/externalweblinks`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/configuration/externalweblinks' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `[].id` | integer (int32) | The link's identifier, and the value the update and delete endpoints take. Allocated per tenant, so it is **specific to one tenant** and carries no meaning elsewhere — never hard-code it, and do not assume ids are contiguous, since deleted links leave gaps. |
| `[].linkTypeId` | integer (int32) | The category this link is filed under, matching an `id` from [the external web link types list](get-all-external-web-link-types.md). Required on every link and always a real type — but the type's name is not included here, so join locally to label it. Tenant-specific, like the type ids themselves. On create and update, a value that does not exist is rejected with `External Web Link Type Id ... not found.` |
| `[].description` | string | The link's display label — the caption on the tile or menu item. Maximum 255 characters, never `null`, and required when creating or updating a link ("Invalid request: No description provided."). Free text the operator controls, so do not match on it. |
| `[].url` | string | The destination the link opens. Maximum 255 characters and never `null`. Validated on create and update as an **absolute `http` or `https` URI** — relative paths, `mailto:` and other schemes are rejected as not a valid URL — so what you receive is always absolute and web-schemed. Nothing checks that the destination is reachable, so expect dead links. |
| `[].image` | string | URL of the icon or thumbnail shown with the link. No length limit. **Optional and frequently `null`** — plan a placeholder rather than assuming an image exists. When present it has passed a pattern check requiring the value to end in `.svg`, `.jpeg`, `.jpg`, `.gif` or `.png`, case-insensitively; that check accepts both absolute `http`/`https` URLs and bare filenames, so unlike `url` this is not guaranteed to be absolute. Resolve it against your own base when it is not. |
| `[].targetType` | string | How the link should be opened — a new tab, the same window, an embedded view, and so on. Maximum 40 characters and never `null`; required when creating or updating a link ("Invalid request: No target type provided."). **The permitted values are not constrained**: any non-empty string within the length limit is accepted and kept verbatim, so handle unrecognised values defensively and fall back to a safe default rather than failing. |
| `[].domainBrowsing` | boolean | Whether the link may browse within its own domain rather than being pinned to the exact URL — relevant when the link opens inside an embedded browser. Never `null` in practice, even though the type shown permits null. Not validated on create or update beyond being a boolean. |
| `[].status` | string | Whether the operator has the link switched on. Maximum 40 characters. Create and update accept only `Active` or `InActive`, compared case-insensitively, and rejects anything else with a message saying status must be either 'Active' or 'InActive' — but the field is **optional on create and update**, so you will see `null` on links saved without one, and the casing you receive is whatever was sent. Compare case-insensitively. **This endpoint does not filter on it**, so excluding inactive links is your responsibility. |

## Sample response

```json title="200 OK"
[
  {
    "id": 12345,
    "linkTypeId": 12345,
    "description": "string",
    "url": "string",
    "image": "string",
    "targetType": "string",
    "domainBrowsing": true,
    "status": "string"
  }
]
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | Not returned in practice: the endpoint takes no parameters and applies no validation. The validation messages quoted above are returned by the create and update endpoints, not this one. Do not expect a meaningful message here. |
| `500` | Internal server error | Any unexpected server-side failure while reading the links. The response is a bare status code with **no body**. Retry with backoff. |