Skip to main content

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.
  • null clears an optional attribute.
  • Arrays are replaced, not appended.
  • Optional top-level lock_version enables 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:

AttributeWriteRead
Single selectOption UUID or current valueOption UUID
Multi selectArray of option UUIDs/current valuesArray of option UUIDs
stateState UUID or current valueState UUID
tagsArray of UUIDs, labels, or reference objectsArray of {id, label, color}
required_skills / provided_skillsArray of UUIDs, labels, or reference objectsArray of {id, label}
Owning relationshipArray of record UUIDs or {record_id}Array of {record_id, object, display_name}
Managed reverse relationshipNot writableArray of {record_id, object, display_name}
locationAddress, coordinates, or tracking objectStored structure, enriched with available position data
raw_jsonAny JSON object, array, string, number, or BooleanThe same document as JSON; key order and number formatting are normalized
rich_textHTML fragment in the supported subset, or plain textCanonical normalized HTML string
full_name{title?, first_name?, last_name?} with at least one name componentSame 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:

ParameterMeaning
pageZero-based page number
sizePage size
sortRepeatable attribute:asc / attribute:desc, or one to-one hop such as manufacturer.name:asc
includeRepeatable reference attribute to expand
searchLiteral 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:

AttributeREST operators
ideq, ne, in, gt, gte, lt, lte
text, email, phoneeq, ne, in, contains, starts_with, ends_with, is_null
numeric, date, date_timeeq, ne, in, gt, gte, lt, lte, is_null
booleaneq, ne, is_null
single select, stateeq, ne, in, is_null
multi selectin (any of), contains (all of), is_null
raw_jsonis_null
rich_textcontains (plain-text projection), is_null
full_namecontains (combined display), is_null; sortable by last then first name
linkscontains (labels and URLs), is_null
relationships, tags, skillsNested target filter
location, lock_versionNot 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.