Creating & Updating Resources
This page describes the write model for the REST API: how creates, partial updates, full replacements, field clearing, and concurrency control behave. It is the contract every write endpoint follows.
:::note Target contract
This describes the intended write contract for /api/v2. Most resources already follow it;
a few older endpoints are still being aligned. When an endpoint's behaviour differs from what is
described here, the behaviour described here is the direction of travel β file it as a bug.
:::
Creating resources (POST)β
Create a resource by POSTing to its collection. On success the API returns 201 Created with
the full created resource in the body:
curl -X POST "https://api.tourfold.com/api/v2/areas" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Vienna North",
"color": "#3366FF",
"description": "Alpine Facility Services area north of the Danube"
}'
{
"id": "a1b2c3d4-e5f6-4a1b-8c9d-123456789abc",
"name": "Vienna North",
"color": "#3366FF",
"description": "Alpine Facility Services area north of the Danube",
"lock_version": 0
}
Every 201 Created response also includes an absolute Location header containing the canonical
URL of the new resource:
Location: https://api.tourfold.com/api/v2/areas/a1b2c3d4-e5f6-4a1b-8c9d-123456789abc
For a batch create that produces several resources, Location identifies the collection because
there is no single canonical resource URL.
Retrying createsβ
Tour creation currently has no HTTP request-replay key. Each successful request creates an independent Tour, including requests with the same template and tour date. After a timeout or lost response, verify the result before submitting another creation. Workflow execution receipts protect retries inside their documented execution boundary; they do not make independent HTTP requests retry-safe.
Work queued with a Vehicle's connected-car provider (authorization operations, data operations and
phone-fix predictions) takes a required request_id chosen by the client. Repeating it returns the
operation already queued, in its current state; repeating it for a different request of the same kind on
the same connection returns 409 https://problems.tourfold.com/vehicle-provider-connections/request-id-reused.
Keys are kept per kind: authorization operations, data operations and phone-fix predictions each have their own.
See Vehicle locations.
Batch commandsβ
A selective batch command uses POST to an explicit action URL such as /batch. Its contract
states which entries it applies, whether omitted entries stay unchanged, and whether an empty
batch is a no-op. A command that returns the resulting configuration uses 200 OK; the 201
creation rule applies when the operation creates resources. PUT always retains replacement
semantics and must not be used for a selective batch update.
Partial updates (PATCH)β
Updates are PATCH with partial (merge) semantics β you send only the fields you want to
change. This follows RFC 7386 JSON Merge Patch:
- A field omitted from the request body is left unchanged.
- For clearable optional fields, an explicit
nullclears the stored value (see below). - Validation and uniqueness checks run only for the fields you send.
Send Content-Type: application/merge-patch+json. The same body is also accepted as
application/json (an alias with identical omit/null semantics) so generic HTTP clients
keep working.
# Rename the area, leave color and description untouched
curl -X PATCH "https://api.tourfold.com/api/v2/areas/a1b2c3d4-e5f6-4a1b-8c9d-123456789abc" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/merge-patch+json" \
-d '{ "name": "Vienna North & Central" }'
Clearing an optional field (null)β
For fields that are optional and clearable, send an explicit null to remove the stored
value. Omitting the field leaves it unchanged; only an explicit null clears it.
# Clear the description, keep everything else
curl -X PATCH "https://api.tourfold.com/api/v2/areas/a1b2c3d4-e5f6-4a1b-8c9d-123456789abc" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/merge-patch+json" \
-d '{ "description": null }'
Fields that are required cannot be cleared this way. Sending null for a required field (or
for a field that is required for a dependent operation, such as an invoice-relevant billing field)
returns 422 Unprocessable Entity with a problem+json body, rather than silently ignoring it.
For fixed API string fields, clearing takes an explicit null β an empty string does not clear a field and is not accepted.
{"description": ""} returns 422 with field-required for description; use
{"description": null} to clear it, or omit the key to leave it unchanged. The same applies on a
create: omit the key rather than sending "". Workspace-defined record text attributes instead
validate empty strings as values against their configured attribute schema; see
Text values.
Full replacement (PUT)β
PUT is used only where whole-set, declarative replacement is the contract β not as a general
update verb. Where a PUT endpoint exists, it replaces the entire target set: the body you send
becomes the new state, and anything absent from the body is removed. An empty array clears the set.
# Replace a user's skill set entirely β sending [] removes all skills
curl -X PUT "https://api.tourfold.com/api/v2/users/{user_id}/skills" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"skill_ids": [
"00000000-0000-4000-8000-000000005101",
"00000000-0000-4000-8000-000000005102"
]
}'
To clear Jonas's whole skill set, replace it with an empty set:
curl -X PUT "https://api.tourfold.com/api/v2/users/{user_id}/skills" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "skill_ids": [] }'
If you want to change one attribute of a resource, use PATCH on the resource. Reach for PUT
only when the endpoint is explicitly a set-replacement (e.g. tags, skills) or a declarative schema
replacement. Vehicle source selection uses a partial association update:
PATCH /api/v2/vehicle-device-associations/{association_id} with is_location_source.
Object and Vehicle schemas use the same editing pattern:
| Intent | Objects | Vehicles |
|---|---|---|
| Change names, slug or display template | PATCH /definitions/objects/{definition_ref} | PATCH /definitions/vehicles/{definition_ref} |
| Edit one attribute | PATCH /definitions/objects/{definition_ref}/attributes/{attribute_ref} | PATCH /definitions/vehicles/{definition_ref}/attributes/{attribute_ref} |
| Replace the authored schema | PUT /definitions/objects/{definition_ref} | PUT /definitions/vehicles/{definition_ref} |
Definition PUT requires slug, name and attributes. Missing attributes returns 422;
attributes: [] explicitly removes all owned fields, subject to data and dependency guards.
Native, inherited and generated attributes are preserved and must be omitted from the request.
Omitting display_template resets it. Supply attribute and choice IDs to preserve their identities
through renames. The complete candidate is validated and committed atomically, including bulk swaps
and generated reverse relationships; a failed replacement leaves both the schema and records unchanged.
Metadata PATCH never replaces attributes. Both methods accept the original optional lock_version.
For example, suppose an Object definition asset or a Vehicle definition bicycle has two
owned attributes, serial_number and notes, at version 4. This metadata PATCH preserves both
attributes and their values:
{ "name": { "en": { "plural": "Fleet assets" } }, "lock_version": 4 }
To deliberately remove notes, send a full PUT to the same definition URL. Use that definition's
own slug (asset for the Object example, bicycle for the Vehicle example):
{
"slug": "bicycle",
"name": { "en": { "singular": "Fleet asset", "plural": "Fleet assets" } },
"attributes": [{ "slug": "serial_number", "type": "text" }],
"lock_version": 5
}
The retained slug preserves serial_number and its values; omitting notes removes it and its
values if no dependency prevents deletion. This example assumes its original Text configuration
was optional and not unique. Preserve any other intended configuration in a replacement. Both
families return the complete effective definition at the new version after a change.
Task schemas follow the same PATCH/incremental-attribute/PUT pattern at /definitions/tasks.
Their PUT additionally requires the immutable execution_type. They contain authored attributes
only and do not accept display templates. Their optional natural-ID prefix is presentation metadata;
all Task definitions share one numeric sequence. Used Task definitions apply a
conservative change allowlist instead of scanning existing values: structural changes and required
additions are rejected. See Task definitions.
Removing choices from definitionsβ
Removing a select option or state that is still stored in Object or Vehicle records returns
409 resource-conflict. This applies to attribute PATCH, definition PUT, and the Object
option/state DELETE routes, including multiselect values. Update or clear those record values
first; a rejected change leaves the definition and records unchanged. Preserve choice IDs when
renaming labels or values. Deleting an entire attribute follows that owner's deletion rules.
Tasks retain their stricter tasks/definition-in-use guard for structural changes to definitions
used by Tasks, templates or workflows.
Immutable fieldsβ
Some fields are fixed at creation and cannot change on update (for example an SMS gateway's
type). Sending a value that contradicts the stored one is rejected with 422, not silently
ignored, so you never believe a change took effect when it did not.
Optimistic concurrency (lock_version)β
Most writable resources expose a lock_version integer that increments on each successful write.
To guard against lost updates when several clients edit the same resource, include the
lock_version you last read in your write body:
curl -X PATCH "https://api.tourfold.com/api/v2/areas/a1b2c3d4-e5f6-4a1b-8c9d-123456789abc" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Vienna North & Central", "lock_version": 3 }'
- If the supplied
lock_versionmatches the stored version, the write proceeds and the version increments. - If it does not match (someone else wrote in the meantime), the API returns
409 Conflictwith problem typeresource-conflict. Re-read the resource, reconcile, and retry. lock_versionis optional: omit it (or sendnull) to skip the check and perform a last-write-wins update.- Deletes never take a
lock_version.DELETErequests carry no body; a delete always applies to the current stored version unconditionally. - Device telemetry does not advance
lock_version. Reported position, battery and software are stored ascurrent_state, not on the device record, so a pending edit still saves. Only a report that changeskind,platform,device_model,device_identity_idorprovisioning_stateupdates the record and its version. - Exception β per-tenant settings singletons: a few small workspace-configuration endpoints
(
/document-management/settings,/mcp/settings,/ai-assistant/settings, and/geoservices/settings) have nolock_versionand always apply last-write-wins. Each is a single row per workspace edited by one administrator through a purpose-built toggle, so there is no concurrent lost-update scenario to guard./tenantand/billing/profileare singletons too but do exposelock_version, because they are compound records edited by multiple admins.
Success status and response shapeβ
Create and update endpoints return the full resource after the write, so you always see the
resulting state (including the new lock_version) without a follow-up GET. A synchronous
operation that returns a representation uses 200 OK (or 201 Created for a create).
An operation that completes successfully and intentionally has no response representation
returns 204 No Content with an empty body. This is the usual contract for deletes and bodyless
actions such as unassign, remove, or disable. A delete that deliberately returns the deleted
resource or an updated aggregate instead uses 200 OK; 204 is not applied mechanically to every
DELETE.
Work accepted for asynchronous processing uses 202 Accepted. Incoming webhook endpoints follow
the sender's acknowledgement contractβtypically an explicit 200 or 202βrather than being
changed to 204 solely for consistency.
Responses omit ordinary resource fields that have no value β so a field you just cleared with null comes back
absent, not as "field": null. Treat a missing key as "not set". See
Basics β Optional fields and null for the full convention,
and Errors for the problem+json error format.
Field type mismatchesβ
A request field whose value has the wrong JSON type or shape β a string where a number is
expected, a number or boolean where a string is expected, 1.5 for an integer field,
or an object where an array is expected β is rejected with
422 Unprocessable Content, top-level problem type validation-failed, with
errors[].type set to https://problems.tourfold.com/field-type-invalid and an errors[].pointer
identifying the offending field (e.g. #/lock_version, #/tag_ids/0). This is the same
errors[] shape as every other field validation, so you can bind the message to the input
without special-casing. A body that is not valid JSON at all (a syntax error, a truncated
payload) is a 400 Bad Request instead.
JSON scalar values are not converted between strings, numbers and booleans. For example,
{"name":123} is rejected at #/name; send {"name":"123"} if that is the intended text.
Likewise, use true rather than "true" for a boolean and 3 rather than "3" for an integer.
This applies to nested fields and array elements too. Query and path parameters still use their
documented URL text formats.
Custom to-one relationships are an exception: after clearing, the readable relationship remains
present as null in data. Unreadable relationships are omitted.