Flighterz Developer Data API
Sync your company travel data into your ERP, data warehouse or finance system. Keys are issued from your business portal.
This API is read and sync only. It exposes read endpoints and signed change notifications. It can never search, book, issue, change or cancel a reservation.
Authentication
Pass your API key as a Bearer token on every request over HTTPS. Keys belong to one company account, so you only ever read your own data.
curl https://flighterz.com/api/v1/me \
-H "Authorization: Bearer flz_live_xxxxxxxxxxxx"Base URL: https://flighterz.com/api/v1
Scopes
Each key carries a set of read scopes. An endpoint returns insufficient_scope if the key is missing its scope.
account:read | Read the company profile, plan and wallet balance. |
employees:read | Read the employee directory. |
org:read | Read departments, cost centers and projects. |
trips:read | Read trips and their itineraries. |
bookings:read | Read flight and service bookings and tickets. |
invoices:read | Read tax invoices and statement entries. |
budgets:read | Read budgets and live committed spend. |
reports:read | Read aggregated spend analytics. |
Endpoints
| Endpoint | Scope | Description |
|---|---|---|
GET/me | account:read | Company profile, plan and wallet. |
GET/employees | employees:read | List employees. Paginated. |
GET/employees/{id} | employees:read | One employee. |
GET/departments | org:read | List departments. |
GET/cost-centers | org:read | List cost centers. |
GET/projects | org:read | List projects. |
GET/trips | trips:read | List trips. Filters: status, departmentId. |
GET/trips/{id} | trips:read | One trip with its bookings. |
GET/bookings | bookings:read | List flight bookings. Filters: status, tripId. |
GET/bookings/{id} | bookings:read | One flight booking by id or reference. |
GET/service-bookings | bookings:read | List hotel, activity and transfer bookings. |
GET/invoices | invoices:read | List tax invoices. |
GET/budgets | budgets:read | Budgets with live committed spend. |
GET/reports/spend | reports:read | Aggregated spend over twelve months. |
List endpoints are cursor paged: pass ?limit= (max 200) and ?cursor= from the previous meta.nextCursor. Amounts are in halalas (SAR times 100).
Responses
Every success returns a data field, and list responses add a meta with pagination.
{
"data": [ { "id": "...", "reference": "TRP-ABCDE", "status": "TICKETED" } ],
"meta": { "limit": 50, "count": 50, "nextCursor": "clx..." }
}Errors return an error object with a stable code and a human message.
{ "error": { "code": "insufficient_scope", "message": "This key is missing the trips:read scope." } }Rate limits
Live keys allow 120 requests per minute; sandbox keys allow 60. Each response carries X-RateLimit-Limit and X-RateLimit-Window headers, and a 429 includes Retry-After.
Webhooks
Register HTTPS endpoints in your portal and subscribe to events. When something changes we post a signed JSON event so you can pull the current state from the read endpoints.
booking.created | A corporate flight booking was recorded. |
booking.issued | A corporate flight booking was ticketed. |
service_booking.created | A corporate hotel, activity or transfer booking was recorded. |
trip.created | A new trip was opened for the company. |
subscription.updated | The company plan or status changed. |
Verify the signature
Every delivery carries an X-Flighterz-Signature header. Recompute the HMAC over the timestamp and raw body with your endpoint secret, and reject an old timestamp to prevent replay.
// Header: X-Flighterz-Signature: t=1700000000,v1=<hex>
import crypto from "node:crypto";
function verify(rawBody, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < toleranceSec;
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}Deliveries retry with exponential backoff up to eight attempts. Respond with any 2xx to acknowledge.
Sandbox
Create a sandbox key (flz_test_) to build against the same read endpoints at a lower rate limit before you switch to a live key.