Skip to main content

Your first Tourfold data flow

This walkthrough builds a small but complete integration around an equipment register. You will define the schema, create a record, find it by a business key, query it through both API styles, and optionally observe the next change through a signed webhook.

Run it in a development workspace: the first request creates a real object definition.

Before you startโ€‹

Use a server-to-server OAuth client or a user token. The caller needs these grants for the complete walkthrough:

PartRequired grants
Read and create the object definitionschemas:write
Read, create, and update recordsobjects:records:read, objects:records:create, objects:records:update
Optional webhookwebhooks:create

Set two shell variables. Keep the token out of shell history in a real environment; an interactive prompt or secret manager is safer than the literal placeholder shown here.

export TOURFOLD_API="https://api.tourfold.com/api/v2"
export TOURFOLD_TOKEN="YOUR_ACCESS_TOKEN"

If you still need an access token, start with Authentication.

1. See what the workspace already knowsโ€‹

The object catalog is the discovery surface for both REST and GraphQL. It contains standard objects, system projections, and definitions created by your workspace.

curl -fsS "$TOURFOLD_API/definitions/objects?size=100" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
| jq '.items[] | {id, slug}'

An object remains visible as metadata even when the caller cannot read its records.

2. Define an equipment objectโ€‹

This definition has a unique business key, a defaulted Boolean, and a controlled category. Slugs are the field names used in record JSON and in the generated GraphQL schema; localized names are UI labels.

curl -fsS -X POST "$TOURFOLD_API/objects" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "equipment",
"name": {
"en": {"singular": "Equipment item", "plural": "Equipment"},
"de": {"singular": "Anlage", "plural": "Anlagen"}
},
"display_template": "{{name}} ({{asset_tag}})",
"attributes": [
{
"slug": "name",
"type": "text",
"name": {"en": "Name", "de": "Name"},
"config": {"is_required": true, "max_length": 160}
},
{
"slug": "asset_tag",
"type": "text",
"name": {"en": "Asset tag", "de": "Anlagenkennzeichen"},
"config": {"is_required": true, "is_unique": true, "max_length": 40}
},
{
"slug": "category",
"type": "select",
"name": {"en": "Category", "de": "Kategorie"},
"options": [
{"value": "hvac", "title": "HVAC"},
{"value": "elevator", "title": "Elevator"},
{"value": "lighting", "title": "Lighting"}
]
},
{
"slug": "operational",
"type": "boolean",
"name": {"en": "Operational", "de": "Betriebsbereit"},
"config": {"default": true}
}
]
}' | jq '{id, slug, lock_version, attributes: [.attributes[] | {id, slug, type}]}'

Tourfold assigns immutable UUIDs to the object, its attributes, and its select options. Store those IDs when your integration owns schema changes; they let you distinguish a rename from deletion followed by creation. The returned lock_version protects later schema writes from lost updates.

If equipment already exists, do not blindly delete it. Inspect the definition and either use another slug or follow the schema evolution playbook.

3. Create a recordโ€‹

Record data is keyed by the attribute slugs you just declared. Defaults are applied when a field is omitted.

RECORD_ID=$(
curl -fsS -X POST "$TOURFOLD_API/objects/equipment/records" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"category": "hvac"
}
}' | tee /dev/stderr | jq -r '.id'
)

The response has system metadata at the top level and typed values under data. It returns the select option's canonical UUID even though the write used the readable hvac value.

4. Read by the business keyโ€‹

Because asset_tag is unique, it can address a record without first knowing the record UUID:

curl -fsS \
"$TOURFOLD_API/objects/equipment/records/by/asset_tag?attribute_value=AFS-RTU-17" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
| jq

Use this endpoint for point lookup. For sets, use the structured query endpoint:

curl -fsS -X POST "$TOURFOLD_API/objects/equipment/records/query" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"operational": {"eq": true},
"category": {"in": ["hvac"]}
},
"sort": ["name:asc"],
"page": 0,
"size": 20
}' | jq '.items'

5. Query the same model with GraphQLโ€‹

GraphQL is a read surface generated from this workspace's object catalog. Download the actual schema before writing or generating queries:

curl -fsS "$TOURFOLD_API/graphql/schema" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-o tourfold-schema.graphql

The equipment root and its fields now exist because the object definition exists:

curl -fsS -X POST "$TOURFOLD_API/graphql" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Accept: application/graphql-response+json" \
-H "Content-Type: application/json" \
-d '{
"query": "query EquipmentForSync { equipment(where: { asset_tag: { _eq: \"AFS-RTU-17\" } }, first: 1) { edges { node { id name asset_tag category operational lock_version } } } }",
"operationName": "EquipmentForSync"
}' | jq

REST and GraphQL deliberately use the same slugs but slightly different operator spelling: REST uses eq; GraphQL uses _eq. Use REST for writes and GraphQL when connected reads would otherwise require several calls.

6. Optional: observe the next changeโ€‹

Create a webhook endpoint only after its public HTTPS receiver verifies Standard Webhooks signatures. The endpoint secret is returned once; store it immediately.

curl -fsS -X POST "$TOURFOLD_API/webhook-endpoints" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Equipment development receiver",
"endpoint_url": "https://integration.example.invalid/tourfold/webhooks",
"signature_scheme": "HMAC_SHA256",
"enabled": true,
"retry": true,
"subscriptions": ["object.equipment.*"]
}' | jq

Then change the record. An omitted key stays unchanged; the supplied value is merged, and lock_version can be included when your process needs compare-and-set behavior.

curl -fsS -X PATCH "$TOURFOLD_API/objects/equipment/records/$RECORD_ID" \
-H "Authorization: Bearer $TOURFOLD_TOKEN" \
-H "Content-Type: application/merge-patch+json" \
-d '{"data":{"operational":false}}' | jq

The receiver gets object.equipment.updated. Deduplicate on webhook-id, verify the signature over the unchanged request bytes, enqueue durable work, and return 2xx within five seconds. See the complete webhook production guide.

Turn the walkthrough into an integrationโ€‹

Before production:

  • keep immutable IDs alongside readable slugs;
  • cache the GraphQL schema with its ETag and regenerate clients when the revision changes;
  • use lock_version when two writers can update the same schema or record;
  • treat batch creates as atomic and webhook delivery as at-least-once;
  • branch on RFC 9457 type values, never human-readable error text; and
  • test schema changes in a separate workspace before applying them to live data.

Continue with the schema evolution and synchronization playbooks.