Tourfold API Overview
Use the Tourfold APIs to automate workflows, integrate with your systems, and power in-product experiences. We support both REST and GraphQL.
Endpoints​
REST
- Production:
https://api.tourfold.com/api/v2/
GraphQL
- Query endpoint (
POST):https://api.tourfold.com/api/v2/graphql - Schema endpoint (
GET):https://api.tourfold.com/api/v2/graphql/schema
References​
-
OpenAPI Reference (REST): /openapi — download the YAML specification
-
Plugin API specifications: Download them from Settings → General → Features & Plugins. See plugin downloads.
-
GraphQL Reference: See
GraphQL overview. -
Objects and Records Guide: See
Objects and Recordsfor the shared REST and GraphQL data model. -
Vehicle Definitions Guide: See Vehicle definitions and attributes for scoped Vehicle records and custom fields.
-
Tasks Guide: See Tasks for backlog CRUD, assignment and record links.
Choose your style​
- REST: Stable, versioned resources for CRUD, pagination, and webhooks. Start with
REST guide,Authentication, andObjects and Records. - GraphQL: Flexible querying and fewer round-trips. Start with
GraphQL overviewandAuth.
Example scenario​
Examples across the API reference follow Alpine Facility Services GmbH, a fictional maintenance company in Vienna. Dispatcher Mara Berger coordinates technician Jonas Leitner and the Vienna North service area, tracks equipment such as Rooftop HVAC Unit RTU-17 and its maintenance requests, stores service manuals, records comments and tags, and forwards lifecycle events to a webhook.
The company, people, IDs, and records exist only to keep examples consistent. Tourfold does not
create this data automatically in your workspace. REST examples show writes and stable resource
representations; the GraphQL examples show how to filter, sort, paginate, and
traverse the same equipment and maintenance_request objects.
Scenario walkthrough​
The operation-level examples in the OpenAPI reference form one short workflow:
- Create the
HVAC maintenanceskill withcreateSkill, create Jonas Leitner withcreateUser, assign the skill throughupdateUserSkills, and create the Vienna North service area withcreateArea. - Define the
equipmentandmaintenance_requestobjects throughcreateObject. The maintenance-request schema declares its typed relationship to equipment and its managed reverse. - Create RTU-17 and the high-temperature request with
createRecord. The request links to RTU-17 through its relationship value; see theObjects and Records relationship guide. - Create the Equipment manuals folder with
createFolder, then request the upload for RTU-17 service manual.pdf throughinitiateDocumentUpload. - Create the
urgentlabel withcreateTagand record Jonas's Replacement filter ordered update withcreateComment. - Send lifecycle events to Alpine's integration by registering
https://maintenance.example.invalid/tourfold/eventswithcreateWebhookEndpoint.
Open each linked operation to switch between its named request and success-response examples. The narrative here supplies the relationships; the OpenAPI reference remains the source of truth for payload fields and schemas.
Errors​
REST uses RFC 9457 problem details. GraphQL returns errors in the GraphQL errors array (usually with HTTP 200 OK). See Errors.
Quick starts​
For a complete first integration—from token and object definition through REST, GraphQL, and a signed webhook—follow Your first Tourfold data flow. It is designed to be run in a development workspace and explains what to keep when you turn the example into a production sync.
REST
curl -X GET "https://api.tourfold.com/api/v2/areas" \
-H "Authorization: Bearer YOUR_TOKEN"
GraphQL
curl -X POST "https://api.tourfold.com/api/v2/graphql" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"query { equipment(first: 5, order_by: [{ name: asc }]) { edges { node { id name asset_tag } } } }"}'