---
title: "Flyo Flight Alerts API | API Reference"
description: "Reference documentation for Flyo's Flight Alerts API: authentication, rate limits, flight-status lookup, leg subscription, snapshot fields, flight status values, and callback webhooks."
url: https://www.flyo.ai/en/api-docs/flight-alert
lang: en
---

# Flyo Flight Alerts API

> External partner integration reference, version 1.1 (29 September 2026).

**URL:** https://www.flyo.ai/en/api-docs/flight-alert

## Getting Started

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.

| Method | External partner endpoint | Purpose |
|--------|---------------------------|---------|
| GET | `/extPartner/api/flight-alerts` | Get all leg snapshots |
| POST | `/extPartner/api/flight-alerts/subscribe` | Subscribe to one leg |

## Authentication

```http
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](https://ext-partner.flyo.ai/). Callback credentials are generated separately by the flight subscription API.

## Rate Limits and Usage

- 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.

## Integration Sequence

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.

## Error Format

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.

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

## Common Errors

| HTTP Status | Error / condition | Action |
|-------------|-------------------|--------|
| 400 | VALIDATION_ERROR | Fix missing/malformed input, past date, airport code, callback URL or string `fid`. |
| 401 | API key required / Invalid API key | Supply an active incoming `X-API-Key`. |
| 404 | FLIGHT_NOT_FOUND | No matching flight/date or requested leg was discovered. Verify the flight details. |
| 404 | NOT_FOUND | Active partner or required stored flight status was not found. |
| 409 | AMBIGUOUS_FLIGHT | More than one matching flight exists for the same route/date. Contact support. |
| 409 | EXTERNAL_FID_ALREADY_REGISTERED | Use the original `fid` for this subscription, or omit `callbackData` to preserve the existing URL and `fid`. |
| 409 | CALLBACK_ALREADY_REGISTERED | Existing subscription has another callback URL. Omit `callbackData` or use the original URL. |
| 429 | Rate limit exceeded | Wait `retryAfter` seconds before retrying. |
| 500 | INTERNAL_ERROR / Authentication error | Unexpected server/configuration failure. Contact support; avoid tight retry loops. |
| 502 | PROVIDER_UNAVAILABLE | Upstream flight status could not be retrieved. Retry later. |
| 502 | INVALID_PROVIDER_DATA | Invalid schedule or airport data was returned upstream. Contact support. |
| 502 | SUBSCRIPTION_FAILED | The upstream tracking subscription could not be confirmed. Retry the same request. |

## Timestamp Interpretation

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.

## Webhooks

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.

```http
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.

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

| Field | Type / interpretation |
|-------|-----------------------|
| `fid` | String. Your external flight ID, echoed exactly from `callbackData.fid`. Use it to identify which flight the alert belongs to. |
| `changes` | Nested object containing changed fields and new values. Missing fields are unchanged; explicit `null` clears a value. |

### 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.

## Get Flight Status

```http
GET /extPartner/api/flight-alerts
X-API-Key: flyo_<issued-key>
```

Returns HTTP 200 with a JSON array of the latest available snapshots for each available leg of the requested flight and date. A single leg still returns an array with one element. There is no success/data wrapper and no pagination.

### Notes

- For a multi-leg flight, an array may contain DEL → MAA and MAA → HYD. Use `departure.airportIata` and `arrival.airportIata` from the desired element in your subscribe request. Ordering is by airport codes, not guaranteed journey order.

### Query Parameters

| Parameter | Required / format | Description |
|-----------|-------------------|-------------|
| `flightNumber` | Yes — string | Airline designator followed by flight digits, e.g. `AI202` or `QP1407`. Uppercased; spaces/hyphens removed. Leading zeros after a two-letter airline code are removed: `ai-00202` becomes `AI202`. The cleaned validator accepts 2-3 alphanumeric prefix characters followed by 1-4 digits. |
| `departureDate` | Yes — YYYY-MM-DD | A real calendar date, on or after today in UTC. Use the scheduled departure date for the leg, e.g. `2026-10-01`. Time, timezone and shortened date formats are not accepted. |

Airport codes are not required for GET. Send scalar strings, not arrays.

### cURL

```bash
curl --get "$BASE_URL/extPartner/api/flight-alerts" \
  --header "X-API-Key: $API_KEY" \
  --data-urlencode "flightNumber=AI202" \
  --data-urlencode "departureDate=2026-10-01"
```

### Response

HTTP 200 — `Content-Type: application/json`, `Cache-Control: no-store`.

```json
[
  {
    "stopover": {"airportIata": null, "city": null},
    "flightNumber": "AI202",
    "isCodeshare": 0,
    "codeshareFlightNumber": null,
    "status": "schedule",
    "airline": {
      "name": "Air India",
      "code": "AI"
    },
    "departure": {
      "airportIata": "DEL",
      "city": "Delhi",
      "terminal": "T3",
      "utcOffsetSeconds": "19800",
      "scheduledTime": "2026-10-01 10:00:00",
      "estimatedTime": "2026-10-01 10:15:00",
      "actualTime": null,
      "gate": "A1",
      "boardingStatus": "check-in"
    },
    "arrival": {
      "airportIata": "MAA",
      "city": "Chennai",
      "terminal": "T1",
      "utcOffsetSeconds": "19800",
      "scheduledTime": "2026-10-01 12:45:00",
      "estimatedTime": "2026-10-01 13:00:00",
      "actualTime": null,
      "baggageBelt": null
    }
  }
]
```

This is a one-leg example; additional legs have the same shape. GET does not return subscription IDs, callback credentials, subscription flags or history. Match callbacks using your external `fid`.

## Subscribe to a Flight Leg

```http
POST /extPartner/api/flight-alerts/subscribe
X-API-Key: flyo_<issued-key>
Content-Type: application/json
```

Enables tracking for one flight/date/departure/arrival combination. A prior GET is optional. Other legs are not automatically subscribed.

### Request Fields

| Field | Required / type | Rules |
|-------|-----------------|-------|
| `flightNumber` | Yes — string | Same normalization and format as GET. |
| `departureDate` | Yes — string | `YYYY-MM-DD`; today or future under UTC validation. |
| `departureAirportIata` | Yes — string | Exactly three alphabetic letters; trimmed and uppercased, e.g. `DEL`. |
| `arrivalAirportIata` | Yes — string | Exactly three alphabetic letters; trimmed and uppercased, e.g. `MAA`. |
| `callbackData` | No — object | Omit or use `null` for a polling-only subscription. |
| `callbackData.fid` | Yes when `callbackData` is supplied — string | Your external flight ID. Non-empty, at most 255 characters. Echoed exactly; use a stable ID such as `booking-flight-42`. |
| `callbackData.callbackUrl` | Required when `callbackData` is supplied — string | Public HTTPS URL. No URL credentials, IP literals, fragments or internal hostnames. Redirects are not followed during delivery. |

Do not supply `auth_header`, `clientId` or `clientName` for flight-alert registration. Flyo generates the callback credential and derives partner identity from authentication. This differs from check-in callback registration.

### cURL

```bash
curl --request POST \
  "$BASE_URL/extPartner/api/flight-alerts/subscribe" \
  --header "X-API-Key: $API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "flightNumber": "AI202",
    "departureDate": "2026-10-01",
    "departureAirportIata": "DEL",
    "arrivalAirportIata": "MAA",
    "callbackData": {
      "callbackUrl": "https://partner.example.com/flight-alerts",
      "fid": "booking-flight-42"
    }
  }'
```

### Response

```json
{
  "success": true,
  "latest_status_snapshot": {
    "stopover": {"airportIata": null, "city": null},
    "flightNumber": "AI202",
    "isCodeshare": 0,
    "codeshareFlightNumber": null,
    "status": "schedule",
    "airline": {"name": "Air India", "code": "AI"},
    "departure": {
      "airportIata": "DEL", "city": "Delhi", "terminal": "T3",
      "utcOffsetSeconds": "19800",
      "scheduledTime": "2026-10-01 10:00:00",
      "estimatedTime": "2026-10-01 10:15:00", "actualTime": null,
      "gate": "A1", "boardingStatus": "check-in"
    },
    "arrival": {
      "airportIata": "MAA", "city": "Chennai", "terminal": "T1",
      "utcOffsetSeconds": "19800",
      "scheduledTime": "2026-10-01 12:45:00",
      "estimatedTime": "2026-10-01 13:00:00",
      "actualTime": null, "baggageBelt": null
    }
  },
  "callbackApiKey": "flyo_cb_<generated-key>"
}
```

| Field | Meaning |
|-------|---------|
| `success` | Boolean; `true` on a successful subscription. |
| `latest_status_snapshot` | Full selected-leg snapshot. |
| `callbackApiKey` | String, returned only when a callback is first registered. Save securely; retries do not return it again. |

Identical retries preserve the subscription and callback credential. Omitting `callbackData` preserves an existing callback. A different callback URL returns 409 CALLBACK_ALREADY_REGISTERED. A different `fid` on the same subscription returns 409 EXTERNAL_FID_ALREADY_REGISTERED. Omit `callbackData` to preserve the existing URL and `fid`. A polling-only subscription can later attach a callback through this external API. No callback rotation, key-recovery or unsubscribe endpoint is currently exposed.

## Snapshot Field Reference

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.

| Field | Typical type | Meaning |
|-------|--------------|---------|
| `flightNumber` | string | Flight number for this leg. |
| `stopover` | object | Always contains `airportIata` and `city`. |
| `stopover.airportIata` | string \| null | Intermediate stop airport IATA code. Always present; may be empty or null. |
| `stopover.city` | string \| null | Intermediate stop city. Always present; may be empty or null. |
| `alternateInfo` | array (optional) | Alternate-route details when available. Omitted when no details have been received. |
| `isCodeshare` | integer \| null | `0` = non-codeshare; `1` = codeshare. Not a JSON boolean. |
| `codeshareFlightNumber` | string \| null | Codeshare / actual operating-carrier flight number; may be blank if not supplied. |
| `status` | string \| null | Current flight status. See Flight Status Values. |
| `airline` | object | Airline information. |
| `airline.name` | string \| null | Airline name. |
| `airline.code` | string \| null | Airline designator derived from `flightNumber`. |
| `departure` | object | Departure information for this leg. |
| `departure.airportIata` | string \| null | Departure airport IATA code. |
| `departure.city` | string \| null | Departure city name. |
| `departure.terminal` | string \| null | Departure terminal, e.g. T3. |
| `departure.utcOffsetSeconds` | string/number \| null | Origin UTC offset in seconds, e.g. `"19800"`. |
| `departure.scheduledTime` | string \| null | Scheduled departure date/time. |
| `departure.estimatedTime` | string \| null | Estimated departure date/time; no prediction fallback. |
| `departure.actualTime` | string \| null | Actual departure date/time, when available. |
| `departure.gate` | string \| null | Boarding gate. |
| `departure.boardingStatus` | string \| null | Boarding/check-in state. See Boarding Status Values. |
| `arrival` | object | Arrival information for this leg. |
| `arrival.airportIata` | string \| null | Arrival airport IATA code. |
| `arrival.city` | string \| null | Arrival city name. |
| `arrival.terminal` | string \| null | Arrival terminal. |
| `arrival.utcOffsetSeconds` | string/number \| null | Destination UTC offset, in seconds. |
| `arrival.scheduledTime` | string \| null | Scheduled arrival date/time. |
| `arrival.estimatedTime` | string \| null | Estimated arrival date/time. |
| `arrival.actualTime` | string \| null | Actual arrival date/time. |
| `arrival.baggageBelt` | string \| null | Baggage reclaim belt/turntable. |

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`.

## Alternate Flight Information

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.

| Field in `alternateInfo[]` | Meaning |
|----------------------------|---------|
| `status` | Alternate flight status string. |
| `departure.city` / `arrival.city` | Departure or arrival location name. |
| `departure.airport` / `arrival.airport` | Departure or arrival airport, when available. |
| `departure.scheduledTime` / `arrival.scheduledTime` | Scheduled time, `YYYY-MM-DD HH:mm:ss`. |
| `departure.actualTime` / `arrival.actualTime` | Actual time, when available. |
| `departure.utcOffsetSeconds` / `arrival.utcOffsetSeconds` | UTC offset in seconds, when available. |

```json
{
  "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"}
      }
    ]
  }
}
```

## Boarding Status Values

Values that can appear in `departure.boardingStatus`.

| Value | Meaning |
|-------|---------|
| `check-in` | Check-in phase. |
| `check-in closed` | Check-in has closed. |
| `boarding` | Boarding is in progress. |
| `last call` | Final boarding call. |
| `gate closed` | Boarding gate has closed. |
| `web check-in` | Web check-in label; may also appear when a more specific boarding state is unavailable. |

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

## Flight Status Values

`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.

| Value | Meaning |
|----------------|---------|
| `schedule` | Scheduled flight. |
| `delay` | Delayed flight. |
| `cancel` | Cancelled flight. |
| `diversion` | Flight diversion reported. |
| `return` | Flight return reported. |
| `departure` | Departure reported. |
| `arrival` | Arrival reported. |
| `diverted flight departure` | Departure of a diverted flight. |
| `diverted flight cancel` | Cancellation of a diverted flight. |
| `diverted flight arrival` | Arrival of a diverted flight. |
| `returned flight departure` | Departure of a returned flight. |
| `returned flight cancel` | Cancellation of a returned flight. |
| `returned flight arrival` | Arrival of a returned flight. |
| `cancel in advance` | Cancellation reported in advance. |
| `circling` | Circling phase reported. |
| `circled` | Circling-related status; do not infer a specific flight milestone from this value alone. |
| `climbing` | Climb phase. |
| `cruising` | Cruise phase. |
| `descending` | Descent phase. |
| `landing` | Landing phase. |

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.

## Before Going Live

- 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 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.

---

## Get an API key

Get your API key from the [Flyo partner dashboard](https://ext-partner.flyo.ai/).

---

_Source: https://www.flyo.ai/en/api-docs/flight-alert_