Partner API v1

Find a Flight Partner API

Production award-seat search for partner products that need clear provenance, privacy-safe enrichment, and reliable handoff rules. The live surface is deliberately narrow, tested, and ready for server-side integration.

OpenAPI YAML OpenAPI JSON

Live base URL: https://api.findaflight.com.au/v1
Live endpoint: POST /v1/search
Direct gateway URL: https://vaqvasz1b3.execute-api.ap-southeast-2.amazonaws.com/v1
Commercial model: Software and data access only; partners handle booking and travel payments.

Quickstart

Make a production search call

Use a partner key with search:write, keep it server-side, and treat warnings as product-critical response data. This request shape is live on the branded API host.

cURL

curl -X POST "https://api.findaflight.com.au/v1/search" \
  -H "Authorization: Bearer $FAF_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-demo-001" \
  -d '{
    "origin": "MEL",
    "destinations": ["SIN", "HND"],
    "departure_date": "2026-09-15",
    "cabin_classes": ["business"],
    "max_results": 10,
    "partner_context": {
      "partner": {
        "partner_tenant_id": "payrewards-demo",
        "partner_user_id_hash": "sha256:example"
      },
      "rewards": {
        "balance_band": "250k_500k",
        "preferred_transfer_partners": ["Qantas", "KrisFlyer"]
      },
      "payments": {
        "volume_band": "50k_250k_monthly",
        "category_mix": ["ATO", "Suppliers"]
      },
      "consent": {
        "personalisation": true,
        "marketing": false,
        "data_sharing": true,
        "profiling": true
      }
    }
  }'

Operational proof

What is live today

Branded hostLive

api.findaflight.com.au routes /v1/* to the v3 Partner API while preserving legacy extension traffic.

Auth boundaryEnforced

Unauthenticated search requests return 401. Active keys are matched by hash and scope.

Production routePOST /v1/search

The live endpoint returns partner-shaped availability, usage units, warnings, and pagination metadata.

ContractOpenAPI 3.1

YAML and JSON specs are served from the portal with the branded production server first.

Authentication

Use an issued partner key as a Bearer token from a server-side service. Keys are stored as hashes only, carry scopes, and should never be embedded in browsers or mobile apps.

Freshness

Every result is shaped around observed time, source type, confidence, warnings, and refresh caveats so partner products can decide what to show, suppress, or recheck.

Privacy

Pass derived context where possible: hashes, tokenised IDs, bands, categories, and consent flags. Raw email, phone, names, loyalty member IDs, and customer PII are excluded from partner context.

Usage

Search calls are metered with tenant, client, endpoint, cache, and result-count context. The response includes the units charged for the request.

Sandbox

Use demo-scoped partner keys, OpenAPI examples, and low-volume smoke searches to validate integrations before production traffic. The same v1 contract is used for search, refresh, alerts, webhooks, usage, and entitlements.

Webhooks

Webhook endpoint registration, event inspection, and HMAC signature contracts are live for server-side partner integrations.

API reference

Production status by route

Every route in this table is enabled on the production v1 API. Use the OpenAPI contract to pin request and response shapes, then run an authenticated smoke before sending partner traffic.

MethodRouteStatePurpose

POST/v1/searchProductionAuthenticated award availability search.

POST/v1/search/flexibleProductionFlexible-date and multi-destination search jobs.

GET/v1/searches/{search_id}ProductionAsync search status and paginated results.

POST/v1/refreshProductionLive refresh requests for routes or availability records.

GET/v1/refresh/{refresh_id}ProductionRefresh job status and result lookup.

GET/v1/availability/{availability_id}ProductionSingle availability record lookup.

GET/v1/coverageProductionCoverage, programme, and caveat reference data.

GET/v1/programmesProductionSupported points programmes.

GET/v1/airlinesProductionSupported airline and source metadata.

POST/v1/alertsProductionCreate saved availability alerts.

GET/v1/alertsProductionList saved availability alerts.

GET/v1/alerts/{alert_id}ProductionRetrieve saved alert detail.

PATCH/v1/alerts/{alert_id}ProductionUpdate saved alert status or expiry.

DELETE/v1/alerts/{alert_id}ProductionDelete saved alerts.

POST/v1/webhooks/endpointsProductionRegister partner webhook destinations.

GET/v1/webhooks/endpointsProductionList partner webhook destinations.

GET/v1/webhooks/eventsProductionInspect recorded webhook events.

GET/v1/usageProductionUsage reporting and billing support.

GET/v1/entitlementsProductionPartner quotas and enabled features.

Response contract

Rank with the fields that matter

Availability is returned with enough context to build a serious partner product: route, programme, source quality, seat-count semantics, points price, usage, and warnings.

route and stopssource_type and confidenceusage unitswarnings

Search response excerpt

{
  "search_id": "d90ee38b-6416-4b86-b493-deec572df632",
  "status": "completed",
  "data": [
    {
      "availability_id": "b0d64f78:1d8d6130",
      "source_type": "indicative",
      "confidence": "high",
      "programme": { "code": "QFF", "name": "Qantas Frequent Flyer" },
      "airline": { "code": "QF", "name": "QF" },
      "route": {
        "origin": "MEL",
        "destination": "SIN",
        "departure_at": "2026-09-15T06:00:00+10:00",
        "arrival_at": "2026-09-15T16:55:00+08:00",
        "stops": 1,
        "stopover_airports": ["SYD"]
      },
      "cabin": "business",
      "seat_count_kind": "unknown",
      "points_price": 101400
    }
  ],
  "usage": {
    "units": 1,
    "unit_type": "cached_search",
    "cache_units": 1
  },
  "warnings": [
    {
      "code": "indicative_results",
      "severity": "warning",
      "message": "Results are indicative and should be refreshed before partner handoff."
    }
  ]
}

Reliability

Handle failure before launch

A polished integration handles API boundaries as product states. Do not ship a partner surface that treats all non-200 responses the same way.

400Invalid search body

Validate airport codes, date format, cabin names, and destination count before retrying.

401Missing or invalid key

Check the Bearer token and keep it server-side.

403Scope denied

Request search:write or the route-specific scope before retrying.

409Idempotency conflict

Reuse the same idempotency key only for the same request body.

429Quota or rate limit

Back off and surface a retry state in the partner product.

5xxService fault

Retry with jitter and preserve the original idempotency key.

PayRewards enrichment

Pass useful context without raw PII

Pay can improve search, ranking, alerts, offers, analytics, and support by sending derived business and loyalty context. The API is designed for bands and tokens, not customer records.

ContextFieldsHandling

Identitypartner_user_id_hash, partner_account_id, tokenised ABNUse hashed or tokenised identifiers only.

Rewardsbalance_band, preferred_transfer_partners, expiry_risk_bandImproves ranking, transfer guidance, and affordability copy.

Paymentsvolume_band, category_mix, lifecycle_stageConnects business spend intent to realistic reward travel options.

Travelhome_airport, destination_regions, cabin_preferenceNarrows search defaults without exposing private itinerary history.

Consentpersonalisation, marketing, data_sharing, profilingControls whether context can shape results, offers, analytics, or support.

Examples

Server-side integration snippets

Keep API keys out of browsers. These examples show the shape expected in a partner backend or BFF layer before rendering results into a PayRewards-style product experience.

TypeScript

type PartnerSearchRequest = {
  origin: string;
  destinations: string[];
  departure_date: string;
  flight_number?: string;
  cabin_classes?: Array<"economy" | "premium_economy" | "business" | "first">;
  max_results?: number;
  partner_context?: Record<string, unknown>;
};

export async function searchAvailability(apiKey: string, body: PartnerSearchRequest) {
  const response = await fetch("https://api.findaflight.com.au/v1/search", {
    method: "POST",
    headers: {
      authorization: `Bearer ${apiKey}`,
      "content-type": "application/json",
      "idempotency-key": crypto.randomUUID()
    },
    body: JSON.stringify(body)
  });

  if (response.status === 401 || response.status === 403) {
    throw new Error("Partner API key is missing, invalid, or lacks search:write.");
  }

  if (response.status === 429) {
    throw new Error("Partner API quota reached. Retry after the response window.");
  }

  if (!response.ok) {
    throw new Error(`Find a Flight API error: ${response.status}`);
  }

  return response.json();
}

Python

import os
import uuid
import requests

response = requests.post(
    "https://api.findaflight.com.au/v1/search",
    headers={
        "Authorization": f"Bearer {os.environ['FAF_PARTNER_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "origin": "MEL",
        "destinations": ["SIN", "HND"],
        "departure_date": "2026-09-15",
        "cabin_classes": ["business"],
        "max_results": 10,
    },
    timeout=20,
)
response.raise_for_status()
print(response.json()["search_id"])