Update external web link

PUT /api/configuration/externalweblinks/{id}

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

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.

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

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.

This page as markdown · All pages · llms.txt