API Documentation

Flyo's external partner APIs let you register flight bookings for automated web check-in, poll the current status of a check-in request, and list all your historical check-in requests.

Because these endpoints are consumed by external systems, all paths below are relative paths. Append them to the deployment-specific host your integration points at.

Every request must include a valid X-API-Key header. Get your API key from the Flyo partner dashboard. The key is static and remains valid until it is revoked from the dashboard; there is no separate expiry or refresh flow.

All request and response bodies use JSON. Timestamps are ISO 8601 UTC strings. IATA codes are exactly three uppercase letters.

External partner endpoints require an API key passed in the X-API-Key header. The key identifies your enterprise and is used for both authentication and per-key rate limiting.

When a request arrives, the key is validated against the database first. Only if it is not found there do we fall back to the legacy environment-based key list.

Validation rules: the header must be present and non-empty; it must match an active key; revoked, disabled, or unknown keys receive 401. There is no token expiry or refresh; a key stays active until revoked. In development mode only, a default environment key can be used for testing. Production integrations must use a real dashboard-issued key.

GET /extPartner/api/webcheckin/requests
X-API-Key: flyo_<issued-key>
Content-Type: application/json

Rate limiting is enforced per API key using a rolling window. Two limits apply independently:

• 60 requests per minute
• 1,000 requests per hour

When either limit is exceeded the API returns HTTP 429 with a retryAfter value in seconds. Wait at least that many seconds before retrying.

Subscribe also consumes a quota unit in addition to the rate limit.

All error responses follow a single JSON shape. The success field is always false. The error field is a stable machine-readable code you can branch on. The message field is a human-readable explanation. Additional context is included only when relevant.

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Missing or malformed request data"
}

The list endpoint uses offset pagination. page is zero-based, so the first page is 0. limit defaults to 25 and is clamped to a maximum of 100. If you omit the parameters you receive page 0 with 25 items.

The response always includes a pagination object with the page you requested, the actual limit applied, the total matching records, and the total number of pages. Use totalPages to know when you have reached the end of the result set.

{
  "success": true,
  "data": [],
  "pagination": {
    "page": 0,
    "limit": 25,
    "total": 47,
    "totalPages": 2
  }
}

When you subscribe a booking with callbackData, Flyo pushes status changes to your callbackUrl instead of requiring you to poll. Webhooks are sent for the event kind webcheckin.update whenever the check-in attempt changes state.

The callbackData object requires callbackUrl, clientId, clientName, and auth_header. The auth_header must be in the format '<Header-Name>: <Header-Value>' and the header name must be either X-API-Key or Authorization. Flyo forwards this header exactly in every webhook request so your endpoint can verify it.

Webhook delivery is handled through an internal SQS queue. Retries and backoff are managed by the queue consumer; your endpoint should respond with a 2xx status code so delivery is considered successful.

Flyo does not sign the webhook body or add a provider signature header. Authenticate the request using the auth_header value you configured.

{
  "occurredAt": "2026-09-02T09:00:00.000Z",
  "checkin_id": "CHK-783245",
  "changes": {
    "status": "COMPLETED",
    "sub_status": "BOARDING_PASS_AVAILABLE",
    "checkin_message": "Check-in completed and boarding passes are available",
    "missing_info": [],
    "boarding_passes": [
      "https://files.example.com/boarding-pass.pdf"
    ]
  }
}