Skip to main content

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 null clears 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:

IntentObjectsVehicles
Change names, slug or display templatePATCH /definitions/objects/{definition_ref}PATCH /definitions/vehicles/{definition_ref}
Edit one attributePATCH /definitions/objects/{definition_ref}/attributes/{attribute_ref}PATCH /definitions/vehicles/{definition_ref}/attributes/{attribute_ref}
Replace the authored schemaPUT /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_version matches 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 Conflict with problem type resource-conflict. Re-read the resource, reconcile, and retry.
  • lock_version is optional: omit it (or send null) to skip the check and perform a last-write-wins update.
  • Deletes never take a lock_version. DELETE requests 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 as current_state, not on the device record, so a pending edit still saves. Only a report that changes kind, platform, device_model, device_identity_id or provisioning_state updates 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 no lock_version and 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. /tenant and /billing/profile are singletons too but do expose lock_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.