Skip to main content

Links

links stores one primary link and optional alternative links, each a URL with an optional human-readable label. Use it for websites, documentation, support addresses or phone links that belong to a record. Ordinary text attributes are unchanged: a text value that happens to look like a URL is never converted.

Valueโ€‹

{
"primary": { "url": "https://example.com/docs", "label": "Documentation" },
"alternatives": [
{ "url": "mailto:support@example.com", "label": "Support" },
{ "url": "https://status.example.com" }
]
}
MemberRules
primaryRequired whenever the value is present. One link object.
alternativesOptional on write, always an array on read. Ordered; at most 10 entries.
urlRequired per link. Trimmed, 1 to 2048 characters, an absolute URL using http, https, mailto or tel. Web URLs need a host.
labelOptional per link. Trimmed, at most 200 characters; blank labels are dropped.

The same URL may appear only once across the primary and the alternatives. Saving or displaying a link never contacts its destination: no previews, no crawling, no metadata.

A supplied value replaces the stored value entirely. To promote an alternative, send the structure with that entry as primary and the former primary in alternatives; the API stores the structure it receives.

Empty valuesโ€‹

A value without a primary link and without alternatives, such as {} or {"alternatives": []}, is empty. It clears the attribute exactly like null: an optional attribute is removed and a required one returns 422 required-field. Alternatives without a primary return 422 links-primary-required.

Validation errorsโ€‹

Error typeCause
type-mismatchThe value, a link or alternatives has the wrong shape; the pointer names the member, for example #/data/website/alternatives/1.
unknown-fieldA member other than primary, alternatives, url or label.
required-fieldA link without url.
links-unsafe-linkA URL on a scheme other than http, https, mailto or tel.
invalid-formatA URL that cannot be parsed, has no host, or contains whitespace or control characters.
string-too-longA url or label exceeds its length limit.
duplicate-itemsThe same URL appears twice; the pointer names the repeated alternative.
too-many-itemsMore than 10 alternatives.
links-primary-requiredAlternatives were supplied without a primary link.

Displayโ€‹

Display templates and compact list cells show the primary link's label, or its URL when it has no label. The Tourfold web app renders every link as its label with the URL as a tooltip; web links open in a new tab with rel="noopener noreferrer", mail and phone links are handed to the device, and a URL on any other scheme is shown as plain text. Consumers rendering stored links should apply the same scheme policy.

Definitionโ€‹

{
"slug": "website",
"type": "links",
"name": {"en": "Website", "de": "Webseite"},
"config": {"is_required": false}
}
ConfigurationBehavior
is_requiredA primary link must be present.
defaultNot available.
is_uniqueNot supported; returns 422 unique-unsupported-type.

Query capabilitiesโ€‹

SurfaceCapability
REST filter_operatorscontains and is_null (is_null only for optional attributes)
REST is_sortablefalse
GraphQL outputRecordLinks { primary: RecordLink!, alternatives: [RecordLink!]! } with RecordLink { url: String!, label: String }
GraphQL filterLinksOperators with _contains and _is_null
GraphQL order_byNot available
SearchLabels and URLs of every link are indexed; member names are not

contains matches the labels and URLs of all links case-insensitively. Equality, prefix and suffix operators return 422 filter-operator-not-applicable; a sort returns 422 unsupported-sort-field.

Integration surfacesโ€‹

Webhook payloads, MCP record tools, workflow record operations and Vehicle definitions carry the same object inside data, exactly as REST returns it, with alternatives always present.