Create external web link

POST /api/configuration/externalweblinks

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

Overview

Creates one external web link — a stored URL that the tenant's front-of-house and member-facing applications render as a link or tile. Each link hangs off a link type, which is the slot in the host application the link fills. Link types are reference data you do not create here; list them with Get all external web link types and send the id you want as linkTypeId.

The identifier is generated by the system — you cannot choose it. On success you get 201 Created with a body of {"externalWebLinkId": 1234}. No Location header is set, so read the id from the body. Keep it: it is the {id} for Update external web link and Delete external web links.

There is no idempotency key and no duplicate detection on URL or description, so retrying a request that already succeeded creates a second link with a new id. If a retry is ambiguous, list the existing links before retrying rather than sending the call again.

The only uniqueness rule is per link type. Each link type carries an allowMultiples flag. When it is false, the type may hold exactly one link, and a second create against it fails with 400 and External Web Link Type Id '{linkTypeId}' does not allow multiple entries. — note that this is a 400, not a 409. When allowMultiples is true, any number of links may share the type.

Validation runs before anything is saved, so a rejected request leaves no partial link.

Endpoint

POST {base_url}/api/configuration/externalweblinks

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Request body

Field	Type	Required	Description
`linkTypeId`	integer (int32)	Yes	The slot the link occupies in the host application, taken from the `id` of an entry returned by Get all external web link types. Link types are existing reference data; this endpoint will not create one for you. A value that matches no type — including the `0` you get by omitting the field — is rejected with `400` and `External Web Link Type Id '{value}' not found.` If the type has `allowMultiples` set to false and a link already uses it, the request is rejected instead with the "does not allow multiple entries" message.
`description`	string	Yes	The human-readable label the host application shows for the link, rather than an internal note — this is the text a member or staff user sees. Maximum 255 characters. Must be present and non-empty; omitting it, or sending `null` or `""`, is rejected with `400` and `Invalid request: No description provided.`
`url`	string	Yes	The destination the link opens. Must be an absolute URL with an `http` or `https` scheme — a relative path, a bare hostname such as `www.example.com`, or any other scheme (`ftp:`, `mailto:`) is rejected with `400` and `URL '{value}' is not a valid URL.` Maximum 255 characters. Must be present and non-empty, or you get `400` and `Invalid request: No URL provided.`
`image`	string	No	Absolute URL of an icon or thumbnail the host application displays alongside the link. Optional — omit it, or send `null` or `""`, and the link is created with no image. When supplied it must be `http` or `https` and the path must end in `.svg`, `.jpeg`, `.jpg`, `.gif` or `.png` (case-insensitive); anything else, including a URL with no file extension, is rejected with `400` and `Image URL '{value}' is not a valid URL.` Maximum 255 characters.
`targetType`	string	Yes	How the host application should open the destination. Must be present and non-empty, or you get `400` and `Invalid request: No target type provided.` The value is not validated beyond that, and whatever you send is saved, up to 40 characters — so a typo is accepted here and only surfaces as a broken link in the consuming application. Gladstone's own staff UI writes `Internal` or `External`; match those exactly unless the application you are integrating with expects something else.
`domainBrowsing`	boolean	No	Whether the host application confines the user to the single page at `url` or lets them browse the wider domain from it. Not validated; saved as given. `true` corresponds to the full-domain option and `false` to single-page-only in Gladstone's staff UI. Omitting it or sending `null` saves `false`.
`status`	string	No	Whether the link is live. Accepts `Active` or `InActive`, matched case-insensitively but saved exactly as you sent it, so send the value in the casing your consuming application compares against. Omitting the field, or sending `null` or `""`, saves `InActive` — a created link is therefore hidden by default and needs a follow-up update, or an explicit `"status": "Active"` here, to appear. Any other value is rejected with `400` and `Invalid request: Status must be either 'Active' or 'InActive'.`

Sample request

cURL

curl -X POST '{base_url}/api/configuration/externalweblinks' \
  -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

Error bodies for the 400s below are a bare JSON string containing the message quoted in the "When" column — not a problem-details object. The exception is a malformed body, which returns a validation problem document (application/problem+json, RFC 7807) with an errors map keyed by field name. Check the shape before parsing.

Status	Meaning	When
`400`	Malformed request body	The JSON is unparseable, the body is missing entirely, or a value is of the wrong type — for example a non-numeric `linkTypeId` or a string `domainBrowsing`. Rejected before any other check runs; the body is a validation problem document.
`400`	No description provided	`description` is missing, `null` or empty. Message: `Invalid request: No description provided.`
`400`	No target type provided	`targetType` is missing, `null` or empty. Message: `Invalid request: No target type provided.`
`400`	No URL provided	`url` is missing, `null` or empty. Message: `Invalid request: No URL provided.`
`400`	URL is not a valid absolute http/https URL	`url` is not parseable as an absolute URI, or its scheme is neither `http` nor `https`. Message: `URL '{url}' is not a valid URL.`
`400`	Image URL is not a valid image URL	`image` is supplied but does not match the expected `http`/`https` form ending in `.svg`, `.jpeg`, `.jpg`, `.gif` or `.png`. Message: `Image URL '{image}' is not a valid URL.`
`400`	Link type does not exist	No external web link type has the supplied `linkTypeId` — including `0`, the value you get by omitting the field. Message: `External Web Link Type Id '{linkTypeId}' not found.`
`400`	Invalid status	`status` is supplied but is neither `Active` nor `InActive` (compared case-insensitively). Message: `Invalid request: Status must be either 'Active' or 'InActive'.`
`400`	Link type already in use and does not allow multiples	The link type exists with `allowMultiples` set to false and already has a link against it. Message: `External Web Link Type Id '{linkTypeId}' does not allow multiple entries.` This is the duplicate case, and it returns `400` rather than `409`.
`403`	Forbidden	The token does not carry the scope this endpoint requires. Anonymous and member tokens are both rejected here; use an integration token.
`500`	Internal server error	An unexpected server-side failure after validation has passed, for example while saving the link. The body is empty; nothing is created. Safe to retry, but confirm the link was not created before you do, since retries are not deduplicated.

This page as markdown · All pages · llms.txt