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:
| Part | Required grants |
|---|---|
| Read and create the object definition | schemas:write |
| Read, create, and update records | objects:records:read, objects:records:create, objects:records:update |
| Optional webhook | webhooks: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
ETagand regenerate clients when the revision changes; - use
lock_versionwhen 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
typevalues, 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.