Natural IDs
Each custom Object definition and each concrete Vehicle definition has an optional natural_id_key, such as
ASSET or BIKE, and its own numbering sequence. A record exposes its current human-readable ID
as a top-level string, for example "natural_id": "BIKE-42". Its UUID id remains the permanent
identity for relationships, updates and synchronization. Without a prefix, the ID is still a string,
for example "natural_id": "42".
Task REST/MCP responses use the same string representation. Task definitions share one workspace-wide Task sequence instead of allocating a separate sequence per definition; see Tasks.
Vocabulary
| API field | Application label | Nature | |
|---|---|---|---|
| Record ID | id | Record ID | permanent UUID; paths, relationships, webhooks, synchronisation |
| Natural ID | natural_id | ID | current human-readable value; what people read and type |
| Prefix | natural_id_key | ID prefix | optional, per definition, editable |
A bare "ID" in the application always means the natural ID, and a UUID is always labelled with its
resource ("Record ID", "Tour ID"). The API never renames id; see the ID fields section of the
REST basics.
Application links
Object and Vehicle record pages address a record by its natural ID or by its record ID. The UUID is checked first and always wins, so existing links keep working:
/app/objects/equipment/EQUIPMENT-117
/app/objects/equipment/117
/app/objects/equipment/6f3d2a10-0000-4000-8000-000000000117
/app/vehicles/bicycles/BIKE-42
/app/tasks?task=INS-123
The definition in the path scopes the lookup, so a natural ID resolves by its number: a link that
still carries a prefix retired by a later natural_id_key change opens the same record, and the
page rewrites the address to the current natural_id. Links the application generates (lists,
search results, "Copy link") use the natural ID. The unique-attribute deep link
/app/objects/{object_ref}/by/{attribute_ref}?attribute_value=… and the Vehicle QR landing page
are unchanged.
Define a prefix
On definition creation (POST) and replacement (PUT), omit natural_id_key or send null for
numeric-only string IDs. When provided, the prefix contains 1–16 uppercase ASCII letters or digits, starting with a letter. Non-null prefixes are unique
across Object and Vehicle definitions in the same workspace. Invalid or duplicate prefixes return
422 with a field error at #/natural_id_key.
New definitions allocate numbers starting at 1. Allocation is concurrent-safe; gaps are normal, including after rolled-back writes. Existing Vehicle numbers are preserved during migration. Do not infer record counts from the largest number.
The schema includes a read-only natural_id attribute with a stable attribute UUID. It cannot be
renamed, deleted or written, including an explicit null or the record's current value. Record
responses expose the ID at the top level, not inside data. Use {{natural_id}} in display templates.
Find a record
Definition-scoped lookup accepts either the number or its current prefix:
GET /api/v2/objects/equipment/records/by/natural_id?attribute_value=42
GET /api/v2/objects/equipment/records/by/natural_id?attribute_value=ASSET-42
GET /api/v2/vehicles/bicycles/records/by/natural_id?attribute_value=BIKE-42
The natural-ID attribute's UUID can replace natural_id in these paths. A valid ID with another
prefix returns 404; it never changes the selected definition. Whitespace, leading zeroes, zero,
negative numbers, invalid prefixes and values outside the positive 64-bit integer range return
422. The built-in Vehicle Object spans definitions and natural IDs are not unique across it.
Use a concrete Vehicle definition for /by/natural_id; family-wide unique lookup is rejected.
Sorts on natural_id use the numeric part within a definition: BIKE-2 precedes BIKE-10.
Family-wide Vehicle sorts compare the prefix (no prefix sorts as an empty string), then the number, with UUID as the stable
pagination tie-breaker. Object REST and GraphQL filters use the current formatted string.
Change a prefix
PATCH /api/v2/definitions/vehicles/bicycles
Content-Type: application/merge-patch+json
{"natural_id_key":"CYCLE","lock_version":3}
This requires schemas:write. Omission preserves the prefix; null clears it. Empty or whitespace-only strings are rejected. The definition's
version and schema token change, while record UUIDs, numbers, versions, timestamps and allocator
positions remain unchanged. All subsequent reads use the new prefix, and the old prefix stops
resolving. Refresh cached labels when processing a definition update. Historical events retain
the representation captured when they were produced.
System- and plugin-managed definitions allow this metadata-only PATCH too. They still reject schema changes, deletion, full replacement, or a PATCH mixing the prefix with any protected field. Use the focused prefix control in definition settings to change only this value.
When creating a definition in the application, a short prefix is suggested from its singular name:
Customer → CUS, Patrol Car → PC, Roadside Assistance Vehicle → RAV. Edit it or clear it for
numeric-only IDs. The suggestion follows name changes only until you edit or clear the prefix.
Devices
Devices use the same string representation, but their prefix is fixed by kind and cannot be
changed:
kind | Prefix | Example |
|---|---|---|
TOURFOLD_APP | MOB | "natural_id": "MOB-12" |
THIRD_PARTY_OSMAND | GPS | "natural_id": "GPS-13" |
TRACKING_DEVICE | TRK | "natural_id": "TRK-14" |
All kinds share one workspace-wide number sequence, so a number identifies at most one Device. The
same representation appears in Device REST, MCP and SSE payloads, in device_natural_id on
Vehicle–Device associations and in Device records read through relationships.
GET /api/v2/devices?natural_id=12
GET /api/v2/devices?natural_id=MOB-12
The natural_id filter accepts the number or its prefixed form. A prefix of another kind, such as
TRK-12 for an app Device, matches nothing. Malformed values return 422 with a field error at
#/natural_id, using the same rules as definition lookups above. Free-text search also matches
an exact prefixed ID, case-insensitively. sort=natural_id:asc orders by the shared number.
This pre-GA correction changes Device natural_id from an integer to a string, including
device_natural_id. Regenerate clients and stop building display labels from the number and kind.
Other unrelated built-in resources retain their existing identifier contracts. The separate enterprise EBA integration retains numeric Vehicle IDs.