Skip to main content

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 fieldApplication labelNature
Record IDidRecord IDpermanent UUID; paths, relationships, webhooks, synchronisation
Natural IDnatural_idIDcurrent human-readable value; what people read and type
Prefixnatural_id_keyID prefixoptional, 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.

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:

kindPrefixExample
TOURFOLD_APPMOB"natural_id": "MOB-12"
THIRD_PARTY_OSMANDGPS"natural_id": "GPS-13"
TRACKING_DEVICETRK"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.