# TrueFlight External API Machine-to-machine API for organizations. Authenticate with `Authorization: Bearer tf_live_...`. This specification documents every shipped route under `/api/external/v1` (locations, schedule resources, CRM, maintenance, LMS, read-only payments, and read-only documents/store/contracts/discovery). Response `data` objects use snake_case fields aligned with the implementation. **Not in this version (by design):** Creating or cancelling reservations (`POST /reservations`, `DELETE /reservations/{id}`, or broad `PATCH` beyond notes) is not exposed until internal schedule validation is shared with this surface. Invoice create/update/void (`POST`/`PATCH`/`DELETE` on `/invoices`) is not exposed here; use in-app billing flows. Payment capture, refunds, and card/ACH money movement are not exposed on this API—only read-only payment records for reconciliation. A future narrowly scoped money API may be specified separately. **Read-only extended APIs:** Document templates/instances, store orders, contracts, and discovery flight products are list/detail only. Mutations stay in governed in-app flows (e-sign, commerce checkout, contract authoring, product catalog) until product and compliance extend this API. Aircraft dispatch check-in is not exposed under `/api/external/v1`. Webhooks: verify `x-tf-signature` (HMAC-SHA256 hex over `timestamp.deliveryId.rawBody` using your endpoint signing secret). **Subscribable webhook `type` values** (non-exhaustive; payload `data` uses snake_case with camelCase mirrors where noted): - `ping` — connectivity test from the developer webhook settings UI. - `reservation.created`, `reservation.updated`, `reservation.cancelled` — schedule changes for subscribed organizations/locations. - `invoice.created`, `invoice.paid` — billing lifecycle signals. - `squawk.created` — enqueued for outbound partner webhooks when a squawk is created through `POST /squawks` (in-app squawk flows use separate product notifications). Pair with `GET /squawks` for reconciliation. - `user.invited` — membership row created/updated for an invite; includes `memberships` (membership id + location id), `email`, `user_id`, `is_new_user`, `send_invitation_email`. - `user.invite_accepted` — invitee accepted (in-app or password-creation flow); includes `membership_id`, `location_id`, `user_id`, `status` (membership status after accept). - `user.status_changed` — emitted when a user is archived or unarchived from the CRM; includes `previous_status`, `current_status`, `previous_is_archived`, `current_is_archived`, `reason` (`archived` | `unarchived`). Other membership status edits may be added over time. Version: 1.0.0 License: Proprietary ## Servers Your deployed TrueFlight app (same host as the web UI). ``` https://{deploymentHost}/api/external/v1 ``` Variables: - `deploymentHost`: Hostname only (no scheme), e.g. app.yourcompany.com Default: "sandbox.trueflight.app" ## Security ### bearerAuth Raw key value including the tf_live_ prefix Type: http Scheme: bearer Bearer Format: API Key ## Download OpenAPI description [TrueFlight External API](https://docs.trueflight.app/_bundle/tf-docs.yaml) ## Meta Service metadata and health ### Health check - [GET /health](https://docs.trueflight.app/tf-docs/meta/gethealth.md) ## Identity Caller and organization context ### Current API key and organization - [GET /me](https://docs.trueflight.app/tf-docs/identity/getme.md) ## Reservations Schedule reservations (list, get, patch notes only—no create/cancel in this API version) ### List reservations - [GET /reservations](https://docs.trueflight.app/tf-docs/reservations/listreservations.md) ### Get reservation - [GET /reservations/{id}](https://docs.trueflight.app/tf-docs/reservations/getreservation.md) ### Update reservation notes - [PATCH /reservations/{id}](https://docs.trueflight.app/tf-docs/reservations/patchreservationnotes.md) ## Invoices Billing invoices (read-only list and detail in this API version) ### List invoices - [GET /invoices](https://docs.trueflight.app/tf-docs/invoices/listinvoices.md) ### Get invoice - [GET /invoices/{id}](https://docs.trueflight.app/tf-docs/invoices/getinvoice.md) ## Aircraft Aircraft resources ### List aircraft - [GET /aircraft](https://docs.trueflight.app/tf-docs/aircraft/listaircraft.md) ### Create aircraft - [POST /aircraft](https://docs.trueflight.app/tf-docs/aircraft/createaircraft.md) ### Get aircraft - [GET /aircraft/{id}](https://docs.trueflight.app/tf-docs/aircraft/getaircraft.md) ### Update aircraft - [PATCH /aircraft/{id}](https://docs.trueflight.app/tf-docs/aircraft/patchaircraft.md) ### Soft-delete aircraft - [DELETE /aircraft/{id}](https://docs.trueflight.app/tf-docs/aircraft/deleteaircraft.md) ## Users Organization users and location memberships (invites, directory) ### List users (location memberships) - [GET /users](https://docs.trueflight.app/tf-docs/users/listusers.md): Returns one row per location membership. Org-wide keys may filter with location_id. Location-scoped keys only see that location. ### Get user and memberships - [GET /users/{userId}](https://docs.trueflight.app/tf-docs/users/getuser.md) ### Invite user to one or more locations - [POST /users/invitations](https://docs.trueflight.app/tf-docs/users/createuserinvitation.md): Creates or reuses an auth user, ensures an org profile, creates pending location memberships, and optionally sends invitation email. role is a custom role name or UUID for this organization. ### Resend invitation email - [POST /users/invitations/{membershipId}/resend](https://docs.trueflight.app/tf-docs/users/resenduserinvitation.md): Only allowed when membership status is pending. ## Locations Organization locations (bases) ### List locations - [GET /locations](https://docs.trueflight.app/tf-docs/locations/listlocations.md) ### Get location - [GET /locations/{id}](https://docs.trueflight.app/tf-docs/locations/getlocation.md) ### Update location - [PATCH /locations/{id}](https://docs.trueflight.app/tf-docs/locations/patchlocation.md) ## Simulators Simulator resources ### List simulators - [GET /simulators](https://docs.trueflight.app/tf-docs/simulators/listsimulators.md) ### Create simulator - [POST /simulators](https://docs.trueflight.app/tf-docs/simulators/createsimulator.md) ### Get simulator - [GET /simulators/{id}](https://docs.trueflight.app/tf-docs/simulators/getsimulator.md) ### Update simulator - [PATCH /simulators/{id}](https://docs.trueflight.app/tf-docs/simulators/patchsimulator.md) ### Disable simulator - [DELETE /simulators/{id}](https://docs.trueflight.app/tf-docs/simulators/deletesimulator.md) ## ReservationTypes Schedule reservation types (per location) ### List reservation types for a location - [GET /reservation-types](https://docs.trueflight.app/tf-docs/reservationtypes/listreservationtypes.md): Org-wide keys must pass location_id query. ### Create reservation type - [POST /reservation-types](https://docs.trueflight.app/tf-docs/reservationtypes/createreservationtype.md) ### Get reservation type - [GET /reservation-types/{id}](https://docs.trueflight.app/tf-docs/reservationtypes/getreservationtype.md) ### Update reservation type - [PATCH /reservation-types/{id}](https://docs.trueflight.app/tf-docs/reservationtypes/patchreservationtype.md) ### Delete reservation type - [DELETE /reservation-types/{id}](https://docs.trueflight.app/tf-docs/reservationtypes/deletereservationtype.md) ## Companies Commercial customers (CRM companies) ### List commercial customers - [GET /companies](https://docs.trueflight.app/tf-docs/companies/listcompanies.md) ### Create company - [POST /companies](https://docs.trueflight.app/tf-docs/companies/createcompany.md) ### Get company - [GET /companies/{id}](https://docs.trueflight.app/tf-docs/companies/getcompany.md) ### Update company - [PATCH /companies/{id}](https://docs.trueflight.app/tf-docs/companies/patchcompany.md) ### Delete company - [DELETE /companies/{id}](https://docs.trueflight.app/tf-docs/companies/deletecompany.md) ## Instructors Instructor directory for a location (memberships); POST invites with default instructor role ### List instructors for a location - [GET /instructors](https://docs.trueflight.app/tf-docs/instructors/listinstructors.md): Org-wide keys must pass location_id query. ### Invite instructor (same as user invite with default instructor role) - [POST /instructors](https://docs.trueflight.app/tf-docs/instructors/inviteinstructor.md) ### Get instructor membership - [GET /instructors/{membershipId}](https://docs.trueflight.app/tf-docs/instructors/getinstructormembership.md) ### Update instructor membership - [PATCH /instructors/{membershipId}](https://docs.trueflight.app/tf-docs/instructors/patchinstructormembership.md) ### Not supported - [DELETE /instructors/{membershipId}](https://docs.trueflight.app/tf-docs/instructors/deleteinstructornotsupported.md) ## Payments Payment records (read-only reconciliation) ### List payments (read-only) - [GET /payments](https://docs.trueflight.app/tf-docs/payments/listpayments.md) ### Get payment (read-only) - [GET /payments/{id}](https://docs.trueflight.app/tf-docs/payments/getpayment.md) ## Maintenance Squawks, maintenance reminders, work orders, and work-order status aggregates (GET /work-orders/summary) ### List squawks - [GET /squawks](https://docs.trueflight.app/tf-docs/maintenance/listsquawks.md) ### Create squawk - [POST /squawks](https://docs.trueflight.app/tf-docs/maintenance/createsquawk.md) ### Get squawk - [GET /squawks/{id}](https://docs.trueflight.app/tf-docs/maintenance/getsquawk.md) ### Update squawk - [PATCH /squawks/{id}](https://docs.trueflight.app/tf-docs/maintenance/patchsquawk.md) ### Delete squawk - [DELETE /squawks/{id}](https://docs.trueflight.app/tf-docs/maintenance/deletesquawk.md) ### List maintenance reminders - [GET /maintenance-reminders](https://docs.trueflight.app/tf-docs/maintenance/listmaintenancereminders.md) ### Create maintenance reminder - [POST /maintenance-reminders](https://docs.trueflight.app/tf-docs/maintenance/createmaintenancereminder.md) ### Get maintenance reminder - [GET /maintenance-reminders/{id}](https://docs.trueflight.app/tf-docs/maintenance/getmaintenancereminder.md) ### Update maintenance reminder - [PATCH /maintenance-reminders/{id}](https://docs.trueflight.app/tf-docs/maintenance/patchmaintenancereminder.md) ### Soft-delete maintenance reminder - [DELETE /maintenance-reminders/{id}](https://docs.trueflight.app/tf-docs/maintenance/deletemaintenancereminder.md) ### List work orders - [GET /work-orders](https://docs.trueflight.app/tf-docs/maintenance/listworkorders.md) ### Create work order - [POST /work-orders](https://docs.trueflight.app/tf-docs/maintenance/createworkorder.md) ### Work order counts by status - [GET /work-orders/summary](https://docs.trueflight.app/tf-docs/maintenance/getworkorderssummary.md): Returns aggregate counts for the organization (and location when the API key is location-scoped). active is draft + in_progress + on_hold. total matches the list endpoint filter scope. ### Get work order - [GET /work-orders/{id}](https://docs.trueflight.app/tf-docs/maintenance/getworkorder.md) ### Update work order - [PATCH /work-orders/{id}](https://docs.trueflight.app/tf-docs/maintenance/patchworkorder.md) ### Cancel work order (sets status cancelled) - [DELETE /work-orders/{id}](https://docs.trueflight.app/tf-docs/maintenance/cancelworkorder.md) ## LMS Training courses, enrollments, exams, and exam attempts ### List LMS courses - [GET /lms/courses](https://docs.trueflight.app/tf-docs/lms/listlmscourses.md) ### Create LMS course - [POST /lms/courses](https://docs.trueflight.app/tf-docs/lms/createlmscourse.md) ### Get LMS course - [GET /lms/courses/{id}](https://docs.trueflight.app/tf-docs/lms/getlmscourse.md) ### Update LMS course - [PATCH /lms/courses/{id}](https://docs.trueflight.app/tf-docs/lms/patchlmscourse.md) ### Delete LMS course - [DELETE /lms/courses/{id}](https://docs.trueflight.app/tf-docs/lms/deletelmscourse.md) ### List LMS enrollments - [GET /lms/enrollments](https://docs.trueflight.app/tf-docs/lms/listlmsenrollments.md) ### Create LMS enrollment - [POST /lms/enrollments](https://docs.trueflight.app/tf-docs/lms/createlmsenrollment.md) ### Get LMS enrollment - [GET /lms/enrollments/{id}](https://docs.trueflight.app/tf-docs/lms/getlmsenrollment.md) ### Update LMS enrollment - [PATCH /lms/enrollments/{id}](https://docs.trueflight.app/tf-docs/lms/patchlmsenrollment.md) ### Delete LMS enrollment - [DELETE /lms/enrollments/{id}](https://docs.trueflight.app/tf-docs/lms/deletelmsenrollment.md) ### List LMS exams - [GET /lms/exams](https://docs.trueflight.app/tf-docs/lms/listlmsexams.md) ### Create LMS exam - [POST /lms/exams](https://docs.trueflight.app/tf-docs/lms/createlmsexam.md) ### Get LMS exam - [GET /lms/exams/{id}](https://docs.trueflight.app/tf-docs/lms/getlmsexam.md) ### Update LMS exam - [PATCH /lms/exams/{id}](https://docs.trueflight.app/tf-docs/lms/patchlmsexam.md) ### Delete LMS exam - [DELETE /lms/exams/{id}](https://docs.trueflight.app/tf-docs/lms/deletelmsexam.md) ### List LMS exam attempts - [GET /lms/exam-attempts](https://docs.trueflight.app/tf-docs/lms/listlmsexamattempts.md) ### Get LMS exam attempt - [GET /lms/exam-attempts/{id}](https://docs.trueflight.app/tf-docs/lms/getlmsexamattempt.md) ### Update LMS exam attempt (grading) - [PATCH /lms/exam-attempts/{id}](https://docs.trueflight.app/tf-docs/lms/patchlmsexamattempt.md) ## Documents Document templates and instances (read-only). E-signature and retention rules are enforced in-app; external API exposes sanitized list/detail for reporting and portals—not for creating or mutating regulated document flows. ### List document templates (read) - [GET /document-templates](https://docs.trueflight.app/tf-docs/documents/listdocumenttemplates.md) ### Get document template (read) - [GET /document-templates/{id}](https://docs.trueflight.app/tf-docs/documents/getdocumenttemplate.md) ### List document instances (read) - [GET /document-instances](https://docs.trueflight.app/tf-docs/documents/listdocumentinstances.md) ### Get document instance (read) - [GET /document-instances/{id}](https://docs.trueflight.app/tf-docs/documents/getdocumentinstance.md) ## Store Store orders (read-only). Checkout, fulfillment, and refunds run through in-app commerce and payments; this surface is for reconciliation and dashboards only. ### List store orders (read) - [GET /store-orders](https://docs.trueflight.app/tf-docs/store/liststoreorders.md) ### Get store order (read) - [GET /store-orders/{id}](https://docs.trueflight.app/tf-docs/store/getstoreorder.md) ## Contracts Contracts (read-only). Authoring, execution, and amendments remain in-app until a future external write contract is specified. ### List contracts (read) - [GET /contracts](https://docs.trueflight.app/tf-docs/contracts/listcontracts.md) ### Get contract (read) - [GET /contracts/{id}](https://docs.trueflight.app/tf-docs/contracts/getcontract.md) ## DiscoveryFlights Discovery flight products (read-only). Product configuration and booking flows stay in-app; list/detail support CRM and marketing integrations. ### List discovery flights (read) - [GET /discovery-flights](https://docs.trueflight.app/tf-docs/discoveryflights/listdiscoveryflights.md) ### Get discovery flight (read) - [GET /discovery-flights/{id}](https://docs.trueflight.app/tf-docs/discoveryflights/getdiscoveryflight.md) ## Reports Pre-aggregated read-only reports for accounting/operations exports. Each report mirrors a CSV historically delivered to customers and supports both JSON (default) and CSV (`?format=csv` or `Accept: text/csv`) responses. Date filtering uses `from`/`to` (`YYYY-MM-DD`); both are optional and default to the last 30 days. Maximum window is 366 days. All reports require the `read` scope. ### Aircraft hours invoice report (read) - [GET /reports/aircraft-hours](https://docs.trueflight.app/tf-docs/reports/getaircrafthoursreport.md): Returns invoice line items billed against an aircraft within the requested invoice-date range. Mirrors the legacy Aircraft Hours CSV. CSV columns: Invoice Date, Aircraft Tail, Customer, Quantity, Amount, Line Item Rate Type. JSON adds line_item_type (the enum classification when set on the line). ### Discovery flights export (read) - [GET /reports/discovery-flights](https://docs.trueflight.app/tf-docs/reports/getdiscoveryflightsreport.md): Returns completed/redeemed discovery flight bookings tied to an invoice within the requested invoice-date range. Mirrors the legacy Discovery Flights CSV. CSV columns: Invoice Date, Rate, Taxes, Total Costs, Start, End, Aircraft, Length (hrs). ### Work order parts usage report (read) - [GET /reports/parts](https://docs.trueflight.app/tf-docs/reports/getpartsreport.md): Returns parts issued on work orders that completed within the requested completed-at date range. Mirrors the legacy Parts CSV. CSV columns: Work Order Number, Work Order Name, Actual Complete Date, Resource, Part Number, Description, Quantity, Buy Cost. Buy Cost is currently always empty/null because TrueFlight does not yet capture per-issuance cost on parts usage; this column is reserved for future use. ### Work order labor/time report (read) - [GET /reports/time](https://docs.trueflight.app/tf-docs/reports/gettimereport.md): Returns labor entries (from both work_order_labor and time_entries.work_order_id) for work orders that completed within the requested completed-at date range. Mirrors the legacy Time CSV. CSV columns: Work Order Number, Work Order Name, Actual Complete Date, Resource, Mechanic, Start Date and Time, End Date and Time, Hours, WI Number, WI Name. JSON additionally exposes source (work_order_labor or time_entries) and notes.