Skip to main content

Synchronize records safely

A reliable synchronization is a small state machine, not a loop that retries every HTTP call. Decide which system owns each value, map stable identities, use the API's replacement semantics intentionally, and combine signed webhooks with periodic reconciliation.

Choose ownership first​

Write down one direction for every synchronized concern:

ConcernPossible ownerWhy it matters
Object and attribute definitionsTourfold administrator or provisioning serviceTwo schema writers can delete each other's declarative fields
Scalar attributeSource system, Tourfold, or explicitly mergedPrevents update loops and last-writer surprises
Relationship edgeThe object containing the declaring relationship attributeManaged reverse fields cannot accept writes
Choice catalogSchema ownerRecord writers must not invent options
DeletionOne authoritative system plus reconciliation policyA missed delete cannot be recovered from current records alone

Do not make both systems authoritative for the same field unless you also define conflict resolution, clock assumptions, and loop suppression.

Build an identity map​

For each workspace, persist:

  • workspace identity;
  • object UUID and current slug;
  • attribute UUIDs and current slugs;
  • option/state UUIDs and current values; and
  • Tourfold record UUID plus the source-system ID.

When possible, model the source-system ID as a unique text attribute. That gives you a readable point lookup:

GET /api/v2/objects/equipment/records/by/source_id?attribute_value=erp-4711

The record UUID is still the primary Tourfold identity. A business key can be renamed or reassigned by the source's own rules; preserve both in your mapping store.

Bootstrap the schema​

  1. Read the complete object catalog and locate objects by persisted ID first, slug second.
  2. Create missing objects and capture every server-assigned child ID.
  3. For declarative PUT, send all attributes owned by that object and their existing IDs.
  4. Omit managed reverse attributes from the target object's replacement document.
  5. Send lock_version; on conflict, fetch and reconcile rather than replaying stale state.

If administrators are allowed to extend the same object, a provisioning service must preserve those fields or own a clearly separated object. Declarative replacement is intentionally not a patch.

Import new records atomically​

For independent records, create one at a time and persist the returned UUID immediately. For connected new records, use POST /api/v2/records/batch: it accepts 1–100 records across objects in one transaction.

{
"items": [
{
"object": "equipment",
"key": "equipment:erp-4711",
"data": {
"source_id": "erp-4711",
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17"
}
},
{
"object": "maintenance_request",
"key": "request:erp-9902",
"data": {
"source_id": "erp-9902",
"title": "Temperature too high on third floor",
"equipment": [{"ref": "equipment:erp-4711"}]
}
}
]
}

Request-local key values exist only inside the batch. A ref links to a sibling item. If any item, constraint, or relationship is invalid, the entire batch rolls back and no returned item should be recorded as created.

Batch create is atomic, but it is not an upsert and does not turn a repeated POST into an idempotent operation. After a lost response, reconcile by your unique source key before deciding whether to create again.

Apply updates with merge semantics​

Record PATCH follows JSON Merge Patch:

Payload stateMeaning
Attribute omitted from dataLeave unchanged
Attribute contains a valueReplace current value
Optional attribute is nullClear it
Writable array is []Replace with an empty set

Send only fields owned by this synchronization. This avoids overwriting Tourfold-managed values and fields owned by another system.

{
"lock_version": 12,
"data": {
"name": "Rooftop HVAC Unit RTU-17A",
"certifications": ["tuv", "iso_9001"]
}
}

An array is always the complete desired value, never an append. Read/merge/write if ownership is shared, and protect that sequence with lock_version. A stale version returns 409; fetch current state, reapply your ownership rules, and retry the newly constructed patch.

Relationship arrays follow the same replacement rule only on the declaring owner attribute. A managed reverse is a read-only projection. If a target-side workflow wants to add or remove an edge, it must patch the corresponding owner record.

Reconcile existing records​

Use POST /objects/{object_ref}/records/query for a flat paged scan. Page size is at most 100. Apply an explicit stable sort and keep the source key and Tourfold ID in the result you process.

{
"filter": {
"updated_at": {"gte": "2026-08-27T00:00:00Z"}
},
"sort": ["updated_at:asc", "id:asc"],
"page": 0,
"size": 100
}

This is a query over current state, not a snapshot-isolated change feed. Records can move between pages while the scan is running, and deleted records are absent. Use overlapping time windows and deduplicate by record ID if you use updated_at as a high-water hint. Periodically run a complete inventory reconciliation so missed deletes and long-lived drift are detectable.

GraphQL is useful when reconciliation needs connected context, but its depth and row-cost limits make it the wrong default for bulk export. Prefer REST paging for bulk movement and GraphQL for targeted graph reads.

Use webhooks as the fast path​

Subscribe to the concrete record events you need or an object pattern such as object.equipment.*. A webhook tells you to process a change quickly; REST tells you the current truth.

Your receiver should:

  1. Verify the signature over the exact request bytes.
  2. Enforce a timestamp tolerance.
  3. Insert webhook-id into a table with a unique constraint.
  4. Durably enqueue the event in the same local transaction.
  5. Return 2xx within five seconds.
  6. Process asynchronously and tolerate unknown payload fields.

Delivery is at-least-once and ordering is not guaranteed. The same webhook-id is stable across retries; deduplicate on it. When ordering matters, compare the event timestamp and finally read current REST state rather than trusting arrival order.

Delivery failures are not a complete delivery ledger: they record messages that failed at least once, not every successful attempt. Monitor exhausted failures, but keep your own processing journal and reconciliation job.

Retry by operation type​

OperationSafe retry strategy
GET / queryRetry transient transport/server failures with bounded exponential backoff
PATCH with lock_versionOn lost response, read current state; on 409, merge and send a newly constructed patch
Declarative schema PUTRead current definition/version and regenerate the complete desired document
Record or batch POSTDo not blind-retry after an ambiguous response; look up unique source keys first
Webhook processingDeduplicate by webhook-id; acknowledge duplicates without applying twice

Validation, authentication, authorization, and schema errors are not transient. Branch on the RFC 9457 problem type and status. Refresh and replay once only for an expired-token 401; changing credentials or grants is required for other authorization failures.

Prevent synchronization loops​

If Tourfold and the source both emit changes:

  • store the last applied source version or content hash;
  • compare owned fields before writing and skip no-op patches;
  • retain correlation information in your processing journal;
  • never route solely on a mutable slug; and
  • make webhook handling idempotent independently of API request idempotency.

A webhook caused by your own write is normal. The receiver should recognize that the desired state is already present and finish without another write.

Production checklist​

  • Each synchronized field and relationship has one documented owner.
  • Mapping keys include workspace, object, and record identity.
  • Source IDs are unique where point lookup is required.
  • POST ambiguity is reconciled before retry.
  • Arrays and owner-side relationships are treated as replacement sets.
  • Concurrent updates use lock_version and a merge policy.
  • Webhooks are signature-verified, durably queued, deduplicated, and processed out of order.
  • Full reconciliation covers missed events and deletions.
  • Logs retain request/correlation IDs but never bearer tokens or webhook secrets.

For schema changes that affect the mapping, see Evolve a live object schema.