Welcome to the TrueFlight External API

This portal documents TrueFlight’s machine-to-machine HTTP API for flight schools and training organizations. Use it to sync schedules, CRM data, maintenance, training (LMS), and billing-adjacent reads with your own systems, data warehouse, or partner tools.

The API reference in this site is generated from the same OpenAPI document linked below. Responses use JSON with a data envelope where noted; field names in payloads are snake_case, matching the live implementation.

You are building a server-side integration (cron jobs, ETL, middleware, or a trusted backend), not a browser client. All routes live under /api/external/v1 on your TrueFlight deployment host—the same hostname you use for the web application. (Default is: https://trueflight.app)

1. Create an API key in the TrueFlight web app under Settings → Developer API. Keys are shown once; store them in a secret manager.

2. Call the API with the header:

   Authorization: Bearer <your_api_key>

   Keys are prefixed (for example tf_live_…) so you can tell environment and type at a glance.

3. Check connectivity with GET /health (no auth required), then GET /me to confirm organization, allowed locations, and key scopes.

4. Respect scopes: read-only operations use read scope; create, update, and delete operations require write scope. The reference marks each operation accordingly.

5. Location context: many resources are scoped to an organization and optionally a location. Location-scoped keys behave predictably; org-wide keys often require a location_id query parameter where the resource is per-base. Details are in each operation’s description.

The current surface includes, subject to your plan and permissions:

• Identity and ops — Health and caller context (/me, including location list where applicable).
• Schedule — Reservations (read and limited update where documented), aircraft, simulators, reservation types, instructors.
• CRM and billing reads — Companies (customers), invoices, read-only payments for reconciliation.
• Maintenance — Squawks, maintenance reminders, and work orders.
• LMS — Courses, enrollments, exams, and exam attempts (including grading updates where documented).
• Read-only depth — Document templates and instances, store orders, contracts, discovery flight products—useful for reporting and portals without mutating regulated flows here.

For every shipped route, the OpenAPI 3.1 description is the contract. Download it for codegen, contract tests, or importing into Postman, Insomnia, or your API gateway.

TrueFlight can POST event payloads to HTTPS endpoints you configure. Each delivery includes headers such as x-tf-signature, x-tf-timestamp, and x-tf-delivery-id.

Verify authenticity by computing HMAC-SHA256 over the canonical string timestamp.deliveryId.rawBody (using your endpoint’s signing secret, as shown once when the endpoint is created) and comparing to the hex signature in x-tf-signature. Treat verification failures as non-retryable for that payload until you fix configuration.

Event types and payload shapes are summarized in the OpenAPI info.description and in the reference; user lifecycle events (invites, acceptances, archive status) are documented there with field notes.

Errors follow a consistent problem style (HTTP status plus a machine-readable type and human-readable detail where applicable). Prefer idempotent retries on 5xx and transient network failures with backoff. Do not log full API keys or webhook signing secrets.

The OpenAPI description is the file this site uses to build the reference and link checker targets in this bundle. It is maintained in lockstep with the application so it is always up-to-date.