Flight Alerts API

Contact the Flyo team to discuss API access, pricing and your expected request volume. Once your account is enabled, use the Flyo partner dashboard to create an API key.

Fetch all legs for a flight number and departure date, subscribe to a selected departure/arrival pair, and receive flight-status changes at your HTTPS callback. Start with a partner account and an API key issued from the Flyo partner dashboard.

For production, set BASE_URL=https://prod-api.flyo.ai; for QA testing, use https://qa-api.flyo.ai. Set API_KEY to the key issued for that environment. Use these variables in the cURL examples, without a trailing slash on BASE_URL. Examples are illustrative, not verified flight schedules; replace dates with today or a future date.

X-API-Key: flyo_<issued-key>

Authenticate requests with your active Flyo API key. Keep the key private and send it in the X-API-Key header. Use your API key for requests to Flyo; the separate callback key verifies notifications sent to your endpoint.

Get your incoming API key from the Flyo partner dashboard. Callback credentials are generated separately by the flight subscription API.

API-key requests are limited to 60 per minute and 1,000 per hour, shared with other endpoints using that key. HTTP 429 includes retryAfter in seconds.

Each successful explicit status GET counts once, even if it returns several legs. Subscribe calls do not add GET usage.

Contact Flyo to confirm the usage allowance and commercial terms for your account.

1. GET status using flight number and date.
2. Select a leg from the returned array.
3. Subscribe with its airports, your callback URL and your external flight ID (fid).
4. Save the returned callback key and verify subsequent POSTs.

A direct subscription without a prior GET is also supported.

Flight handlers normally return the JSON envelope below for failures. Authentication middleware uses human-readable error strings; do not assume every error value is an enum. Inspect HTTP status, error and message together.

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "departureDate must be a valid YYYY-MM-DD date"
}

Expected flight timestamp format is YYYY-MM-DD HH:mm:ss, without an offset. Existing timestamp strings are preserved; database date values are serialized to this local-clock format. Do not automatically interpret these values as UTC.

All flight times, including arrival times, use the departure airport's local time. Flyo does not apply a timezone conversion. The destination offset is metadata; do not assume arrival timestamps have been converted into destination-local time.

Flyo sends flight updates to your registered HTTPS callback URL. Each notification contains your fid and a changes object with updated fields. Match fid to the external flight ID supplied in callbackData.fid when subscribing.

POST /flight-alerts
Content-Type: application/json
Authorization: flyo_cb_<generated-key>

Verify Authorization against the callbackApiKey returned at registration. It is a raw value, without Bearer. It is separate from the X-API-Key used for requests to Flyo. Flyo does not provide a separate HMAC or body-signature header.

{
  "fid": "booking-flight-42",
  "changes": {
    "departure": {
      "gate": "B2",
      "estimatedTime": "2026-10-01 10:30:00"
    }
  }
}

Identifying flight updates

Send fid as a JSON string, for example "00123" or "booking-flight-42". Leading zeros are preserved. Assign a stable fid to each flight leg you subscribe to, store it in your system and use the returned fid to apply changes to the correct flight. Handle duplicate notifications.

The same snapshot shape appears in each GET array element and in latest_status_snapshot on subscribe. The mapper preserves stored values; optional or missing values normally appear as null. Blank strings and zero values can also be present.

The stopover object always contains airportIata and city. Empty strings, whitespace and null values are preserved; absent values appear as null. Changes, including clearing a value, appear under callback changes.stopover.

The optional alternateInfo array provides alternate-route details, for example during a diversion. It appears in GET and subscribe snapshots when details are available; flights without alternate details omit the field. The latest known details remain in the snapshot.

Callback changes includes alternateInfo only when those details change. Replace your saved array with the received array. Omitted fields in the main changes object remain unchanged. All fields within an item are optional and may be null.

{
  "fid": "booking-flight-42",
  "changes": {
    "alternateInfo": [
      {
        "status": "diversion",
        "departure": {
          "city": "Delhi",
          "scheduledTime": "2026-10-01 10:00:00"
        },
        "arrival": {
          "city": "Hyderabad",
          "scheduledTime": "2026-10-01 12:30:00"
        }
      }
    ]
  }
}

Values that can appear in departure.boardingStatus.

Null, blank and additional values may appear. Treat flight and boarding statuses as extensible strings and provide an unknown-state fallback.

status is passed through from the upstream flight data. Match the spelling, spaces and lowercase form exactly. The descriptions are explanatory labels, not a guaranteed transition order.

This is an open value set: the API preserves the stored upstream string, including unfamiliar values or whitespace. Do not replace schedule with scheduled, delay with delayed, or cancel with cancelled. Missing values can be null. Build an unknown-state fallback into your integration.

• Verify the status GET returns every expected leg and includes scheduledTime on both sides.
• Subscribe to the selected airport pair with callbackData.fid and securely save callbackApiKey.
• Verify callback Authorization and match fid to your external flight ID.
• Apply nested changes without erasing omitted fields.
• Test null clearing, unknown statuses and duplicate notifications.
• Confirm each GET increments usage once for multi-leg results.
• Verify that retries preserve your callback registration and credential.

For access, integration assistance or changes to your callback setup, contact the Flyo team. Unsubscribe and callback-key rotation are not currently available through these endpoints.