# Update external web link

`PUT /api/configuration/externalweblinks/{id}`

- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Update external web link](https://support.gladstonesoftware.cloud/reference/configuration/update-external-web-link)

## Overview

Rewrites one external web link — a configured link out to another site, shown to users under a link
type that groups related links together.

**This is a full replacement, not a partial update.** The link is rebuilt entirely from your body, so every field is written on every call and anything
you omit is written as its empty or default value. Two omissions are actively dangerous:

- Omitting `status`, or sending it empty, writes `InActive` — the link is **disabled**, not left as
  it was. This is the documented default.
- Omitting `domainBrowsing` writes `false`.

Read the link first with `GET /api/configuration/externalweblinks/{id}` and send every field back.

`description`, `url` and `targetType` are effectively mandatory even though they are not marked as
required — each is rejected when null or empty, so none of them can be cleared by this call.

Validation runs after the link is confirmed to exist and before anything is written, so a rejected
request changes nothing. On success the response is `204 No Content`.

## Endpoint

`PUT {base_url}/api/configuration/externalweblinks/{id}`

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

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer (int32) | Yes | Numeric identifier of the web link to rewrite, as returned by `GET /api/configuration/externalweblinks`. Checked first: if it does not exist the request fails with `404 External Web Link Id '{id}' not found. Record cannot be updated.` and no body validation is reported. The identifier itself is preserved — it cannot be changed here. |

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `linkTypeId` | integer (int32) | Yes | The link type this link is filed under, which is how links are grouped when they are presented. Must match an existing link type or the request fails with `400 External Web Link Type Id '{id}' not found.` — the types are listed by `GET /api/configuration/externalweblinks`, which returns each link with its type. Omitting it sends `0`, which will not match a type and produces that same `400`. |
| `description` | string | Yes | The link's display text. Effectively mandatory: null or empty is rejected with `400 Invalid request: No description provided.`, so it cannot be cleared. Always overwritten. |
| `url` | string | Yes | The destination the link points at. Effectively mandatory (`400 Invalid request: No URL provided.`) and must be an **absolute** `http` or `https` URL — a relative path, a bare hostname or any other scheme fails with `400 URL '{url}' is not a valid URL.`. |
| `image` | string | No | Icon or thumbnail shown with the link. Genuinely optional: null or empty passes validation and clears any stored image. When supplied it must match a pattern requiring the value to end in `.svg`, `.jpeg`, `.jpg`, `.gif` or `.png`, optionally preceded by an `http`/`https` host — so `https://example.com/image.jpg` and `image.png` are accepted, while `example/image.jpg` fails with `400 Image URL '{image}' is not a valid URL.`. The match is case-insensitive. |
| `targetType` | string | Yes | How the link should be opened or which surface it belongs to. Effectively mandatory (`400 Invalid request: No target type provided.`) but saved verbatim: the only check is that it is non-empty, and there is no enforced list of values. |
| `domainBrowsing` | boolean | No | Omitting it or sending null writes `false` rather than preserving the current setting. |
| `status` | string | No | Whether the link is live. Accepted values are `Active` and `InActive`, matched case-insensitively; anything else fails with `400 Invalid request: Status must be either 'Active' or 'InActive'.`. **Omitting it or sending an empty string writes `InActive`**, so a request that means to leave a live link alone will silently disable it. Always send the value you want. |

## Sample request

```bash title="cURL"
curl -X PUT '{base_url}/api/configuration/externalweblinks/{id}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "linkTypeId": 12345,
  "description": "string",
  "url": "string",
  "image": "string",
  "targetType": "string",
  "domainBrowsing": true,
  "status": "string"
}'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | No body was sent — `Invalid request: No external web links provided.` |
| `400` | Bad request | `description` is null or empty — `Invalid request: No description provided.` |
| `400` | Bad request | `targetType` is null or empty — `Invalid request: No target type provided.` |
| `400` | Bad request | `url` is null or empty — `Invalid request: No URL provided.` |
| `400` | Bad request | `url` is not an absolute `http`/`https` URL — `URL '{url}' is not a valid URL.` |
| `400` | Bad request | `image` was supplied but does not end in a supported image extension — `Image URL '{image}' is not a valid URL.` |
| `400` | Bad request | `linkTypeId` matches no link type, including the `0` sent when the field is omitted — `External Web Link Type Id '{id}' not found.` |
| `400` | Bad request | `status` is neither `Active` nor `InActive` — `Invalid request: Status must be either 'Active' or 'InActive'.` |
| `403` | Forbidden | The token is an anonymous or member token. This endpoint is administrative, and both token types get `403`. |
| `404` | Not found | No link exists with that identifier — `External Web Link Id '{id}' not found. Record cannot be updated.` Checked before the body, so it masks any validation problem. |
| `500` | Internal server error | An unexpected server-side failure, including a failure saving the record. No detail is returned. |