Records
A record is one instance of an object. REST owns record writes and structured queries; GraphQL provides read-only graph queries over the same data.
All record paths accept the object slug or UUID as {object_ref}.
Record envelopeโ
System metadata is top-level, while attribute values are keyed by attribute slug inside data:
{
"id": "6f3d2a10-0000-4000-8000-000000000117",
"definition_id": "11111111-9999-4444-8888-111111111111",
"natural_id": "EQUIPMENT-117",
"display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)",
"created_at": "2026-08-26T09:30:00Z",
"updated_at": "2026-08-26T10:15:00Z",
"lock_version": 1,
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": true,
"maintenance_requests": {
"items": [
{
"record_id": "7a4e2b10-0000-4000-8000-000000000201",
"object": "maintenance_request",
"display_name": "Temperature too high on third floor"
}
],
"page": {
"size": 50,
"total_elements": 1,
"total_pages": 1,
"number": 0
}
}
}
}
definition_id is the immutable UUID of the Object definition. It is present in every canonical
record envelope, including write responses, lists, batches and expanded related records, whether
the request uses the definition slug or UUID. It remains unchanged when the definition is renamed.
display_name is the canonical human-readable record label, using the same renderer as compact
relationship references. A configured display_template takes precedence. Without one, custom objects
automatically choose a populated name/title, a first and last name, a business reference (such as a
case number or licence plate), a unique text value, or up to two short text values, in that order.
Email and phone fields are a final value-based fallback. Empty values, UUID values, descriptions,
booleans, dates, choice IDs and relationships do not become automatic labels. Generic text must be
single-line and at most 80 characters; the complete automatic label is capped at 120 characters.
If no usable value exists, or a manual template renders blank, custom objects use their current
natural ID, for example EQUIPMENT-117. Built-in objects retain their
existing template/UUID fallback. Labels are resolved from current data and attributes; no generated
template is persisted. Setting a template overrides automatic naming; clearing it restores automatic
naming. Labels are not unique identifiers. Clients should use display_name for rows, headings,
breadcrumbs and pickers, and keep using the full id for identity.
Unset optional attributes are omitted from data. System fields are server-set and must not be written
inside data.
To-many relationships use {items, page} under their attribute slug. items contains at most
50 compact record views; page describes the complete readable related set. Empty relationships
have items: [], total_elements: 0, and total_pages: 0. When total_elements exceeds the item
count, load the remaining records through the related-record endpoint. To-one relationships
return one compact reference object or explicit null when unset. Unreadable relationships are omitted.
Createโ
POST /api/v2/objects/equipment/records
Content-Type: application/json
{
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": true
}
}
The response is 201 Created with a Location header and the canonical record.
Record writes are strict. Every key in data must name an attribute on the object; unknown keys return
422 Validation failed with an unknown-attribute sub-problem and a pointer such as
#/data/misspelled. When several keys are invalid, the response reports all of them together.
OpenAPI: createRecord
Update with JSON Merge Patchโ
PATCH uses JSON Merge Patch (RFC 7386):
- An omitted attribute stays unchanged.
- A supplied value replaces the current value.
nullclears an optional attribute.- Arrays are replaced, not appended.
- Optional top-level
lock_versionenables optimistic locking.
PATCH /api/v2/objects/equipment/records/6f3d2a10-0000-4000-8000-000000000117
Content-Type: application/merge-patch+json
{
"lock_version": 1,
"data": {
"operational": false
}
}
A stale supplied version returns 409 Conflict. Omitting lock_version skips the concurrency check and
updates the current version.
For multi-selects and owner-declared relationship attributes, the supplied array replaces the complete
set. [] or null clears it; omitting the attribute preserves it. A materialized reverse relationship
is read-only and returns 422 relationship-reverse-managed if included in record data.
A raw_json document is one attribute value. A supplied document replaces the stored document
entirely, including nested objects; the patch never merges into the stored document. {} and []
are stored documents, not clears. Only a top-level null clears the attribute. See
Raw JSON documents.
A rich_text value is normalized before it is stored, and a document without text content, such as
<p><br></p>, clears the attribute like null. See Rich text.
full_name and links values are one attribute value each: a supplied object replaces the stored
object entirely, so a client changing one member sends the whole structure. An object without
content, such as {} or {"alternatives": []}, clears the attribute like null. See
Full name and Links.
OpenAPI: updateRecord
Value shapesโ
Scalar values read back in the same shape written, with these reference-specific rules:
| Attribute | Write | Read |
|---|---|---|
Single select | Option UUID or current value | Option UUID |
Multi select | Array of option UUIDs/current values | Array of option UUIDs |
state | State UUID or current value | State UUID |
tags | Array of UUIDs, labels, or reference objects | Array of {id, label, color} |
required_skills / provided_skills | Array of UUIDs, labels, or reference objects | Array of {id, label} |
Owning relationship | Array of record UUIDs or {record_id} | Array of {record_id, object, display_name} |
| Managed reverse relationship | Not writable | Array of {record_id, object, display_name} |
location | Address, coordinates, or tracking object | Stored structure, enriched with available position data |
raw_json | Any JSON object, array, string, number, or Boolean | The same document as JSON; key order and number formatting are normalized |
rich_text | HTML fragment in the supported subset, or plain text | Canonical normalized HTML string |
full_name | {title?, first_name?, last_name?} with at least one name component | Same object with trimmed members; blank members omitted |
links | {primary: {url, label?}, alternatives?: [{url, label?}]} | Same object with trimmed members and alternatives always present |
Even a single relationship uses an array; is_multiselect: false limits it to zero or one element.
Resolved references returned by reads are valid write values and can be round-tripped through an owning
relationship attribute. Reverse projections must be changed from their owner side.
Listโ
GET /objects/{object_ref}/records accepts only:
| Parameter | Meaning |
|---|---|
page | Zero-based page number |
size | Page size |
sort | Repeatable attribute:asc / attribute:desc, or one to-one hop such as manufacturer.name:asc |
include | Repeatable reference attribute to expand |
search | Literal case-insensitive substring of the canonical display_name (maximum 256 characters) |
curl -G "https://api.tourfold.com/api/v2/objects/equipment/records" \
-H "Authorization: Bearer YOUR_TOKEN" \
--data-urlencode "sort=name:asc" \
--data-urlencode "page=0" \
--data-urlencode "size=20"
The response uses the standard { "items": [...], "page": {...} } envelope. Unknown query parameters
return 422; dynamic record filters belong to the query endpoint.
search is applied with the normal record permissions before the matching total and page are
calculated. Surrounding whitespace is trimmed; an empty or whitespace-only search returns 422
with a field-required error. Omit search for an unfiltered list. % and _ are literal characters,
not wildcards. The same optional search property is supported by the structured query body and is
combined with filter using AND; MCP records_list and records_query use the same behavior.
Names use the ordinary unexpanded record representation, including current reference labels and
the automatic or empty-record fallback described above. include adds related record data
without changing the searchable name. Automatic names and complex templates may require rendering candidate records in
bounded server-side batches; cost grows with the candidate set. The execution deadline defaults to
10 seconds. If it expires, the entire query returns 503 records/query-timeout, never partial totals.
Narrow a large candidate set with a structured attribute filter when possible.
OpenAPI: listRecords
Structured queryโ
Use POST /objects/{object_ref}/records/query for attribute filters, boolean composition, sorting, and
pagination:
{
"filter": {
"operational": { "eq": true },
"or": [
{ "category": { "in": ["hvac", "ventilation"] } },
{ "replacement_cost": { "gt": 25000 } }
],
"maintenance_requests": {
"priority": { "eq": "urgent" }
}
},
"sort": ["name:asc"],
"page": 0,
"size": 20
}
Keys at the same level are ANDed. Use and, or, and not for explicit composition. Relationship
attributes accept nested filters over the target object, including further relationships, up to four
filter levels.
The operator catalog is type-specific:
| Attribute | REST operators |
|---|---|
id | eq, ne, in, gt, gte, lt, lte |
text, email, phone | eq, ne, in, contains, starts_with, ends_with, is_null |
numeric, date, date_time | eq, ne, in, gt, gte, lt, lte, is_null |
boolean | eq, ne, is_null |
single select, state | eq, ne, in, is_null |
multi select | in (any of), contains (all of), is_null |
raw_json | is_null |
rich_text | contains (plain-text projection), is_null |
full_name | contains (combined display), is_null; sortable by last then first name |
links | contains (labels and URLs), is_null |
| relationships, tags, skills | Nested target filter |
location, lock_version | Not filterable |
is_null is omitted for required attributes. The equivalent GraphQL operators use a leading
underscore, such as _eq and _starts_with, with the same semantics. Text matching is
case-insensitive and accepts literal text, not SQL wildcard patterns. Invalid operator/type combinations
return a field-level 422.
Object metadata advertises the exact capability of every attribute through is_sortable and
filter_operators, so a schema-driven client does not need to hardcode this table. Relationship
attributes are not themselves scalar-sortable, but one hop through a to-one relationship is supported:
{
"filter": { "manufacturer": { "country": { "name": { "eq": "Austria" } } } },
"sort": ["manufacturer.name:asc"]
}
Ordering through a to-many relationship, through more than one relationship, by location, or by
lock_version returns 422 before a database query runs.
For relationships to the system user object, me stands for the calling user in id filters, for
example {"filter": {"owner": {"id": {"eq": "me"}}}, "sort": ["owner.lastname:asc"]}. See
Workspace users as targets.
The response is paged. To continue, repeat the POST with the next page number.
Structured REST record queries have a ten-second execution deadline. Exceeding it returns 503 with
problem type https://problems.tourfold.com/records/query-timeout and data.timeout_ms. Database reads
carry the same bound so timed-out work is cancelled rather than continuing indefinitely.
OpenAPI: queryRecords
Get by ID or unique valueโ
Fetch a record by UUID:
GET /api/v2/objects/equipment/records/{record_id}
Or by a business key:
GET /api/v2/objects/equipment/records/by/asset_tag?attribute_value=AFS-RTU-17
The lookup attribute must have config.is_unique: true. A non-unique attribute returns 422; a missing
or blank attribute_value returns 422 at #/attribute_value; and no match returns 404. Send the value
as the query parameter rather than a path segment so encoded slashes, question marks, hash signs, plus
signs, spaces, and Unicode remain data. Attribute references accept a UUID or current slug; UUID
references survive slug renames. Text keys match the stored value exactly, including case, whitespace
and date/date-time spelling; this is key equality, not chronological comparison. Numeric keys compare
as decimals. Select and state keys accept an option/state UUID or its current value. For attributes
normalized on write, such as phone numbers, use the stored canonical value. Vehicle records expose
the same lookup pattern.
The web app exposes the same lookup as a shareable deep link, so an external system can open a record without knowing its Tourfold id:
/app/objects/{object_ref}/by/{attribute_ref}?attribute_value={value}
The page resolves the record through this operation and then redirects to the record's canonical
/app/objects/{object_ref}/{natural_id} page; record pages accept the natural ID or the record
UUID in that segment (see Natural IDs). Encode attribute_value as a
query parameter exactly as you would for the API call.
OpenAPI: getRecord ยท getRecordByUniqueAttribute
Expand and page referencesโ
Repeat include on record reads to eagerly load named relationships; do not combine names into a
comma-separated value:
GET /api/v2/objects/maintenance_request/records/{record_id}?include=equipment&include=assigned_team
An expanded reference gains a record field containing the complete canonical record envelope โ
id, display_name, timestamps, lock_version, data, and its own relationship preview metadata.
Compact record_id, object, and display_name fields remain beside it, so include is a strict
superset of the ordinary response.
Expansion is one level. Relationships inside the expanded record remain compact references and
are never followed recursively or through cycles. Use GraphQL when the response needs a deliberate
multi-level selection.
Relationship values embedded in data are a bounded preview. Page a large related set through:
GET /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests?page=0&size=20
The response uses {items, page}, ordered stably by record ID. Each item is a typed
{kind, definition_id, record} wrapper containing the target owner's full canonical response. See the
relationship response contract. Vehicle targets currently support paginated GET
only. For an Object target that needs filtering or sorting, use the query companion:
POST /api/v2/objects/equipment/records/{record_id}/related/maintenance_requests/query
Content-Type: application/json
{
"filter": { "status": { "ne": "closed" } },
"sort": ["priority:desc", "created_at:desc"],
"page": 0,
"size": 20
}
It uses the target object's same filters, one-hop to-one sorting, page envelope, and ten-second execution deadline.
OpenAPI: listRelatedRecords ยท queryRelatedRecords
Atomic batch createโ
POST /api/v2/records/batch creates 1โ100 records across objects in one transaction. Every item can have
a request-local key. A relationship value {"ref": "<key>"} links to a sibling record created in the
same batch.
{
"items": [
{
"object": "equipment",
"key": "rtu17",
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17"
}
},
{
"object": "maintenance_request",
"data": {
"title": "Temperature too high on third floor",
"equipment": [{ "ref": "rtu17" }]
}
}
]
}
The operation is atomic: any invalid item or relationship rolls back the complete batch. Results are returned in input order.
OpenAPI: batchCreateRecords
Deleteโ
DELETE /objects/{object_ref}/records/{record_id} returns 204 No Content. Relationship edges pointing
to the deleted record are removed; the related records themselves remain.
OpenAPI: deleteRecord
Errorsโ
Validation failures use application/problem+json with status 422. Field errors include a JSON Pointer,
for example #/data/asset_tag. See Errors for the shared problem format.