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
• GraphQL Reference: See GraphQL overview.

Choose your style

• REST: Stable, versioned resources for CRUD, pagination, and webhooks. Start with REST guide and Authentication.
• GraphQL: Flexible querying and fewer round-trips. Start with GraphQL overview and Auth.

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 custom-object concepts.

Scenario walkthrough

The operation-level examples in the OpenAPI reference form one short workflow:

1. Create the HVAC maintenance skill with createSkill, create Jonas Leitner with createUser, assign the skill through updateUserSkills, and create the Vienna North service area with createArea.
2. Define the equipment and maintenance_request custom objects through createDefinition, then create RTU-17 and the high-temperature request with createInstances.
3. Link the maintenance request to RTU-17 using createRelations.
4. Create the Equipment manuals folder with createFolder, then request the upload for RTU-17 service manual.pdf through initiateDocumentUpload.
5. Create the urgent label with createTag and record Jonas's Replacement filter ordered update with createComment.
6. Send lifecycle events to Alpine's integration by registering https://maintenance.example.invalid/tourfold/events with createWebhookEndpoint.

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

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 } } } }"}'