Developer API

Last updated September 3, 2026

Search our flights, link travellers straight into a booking, and earn commission on what you send. Everything below is served from https://air-viva.com.

Getting access

The affiliate programme is open — anyone can join. Get in touch and tell us who you are and roughly what traffic you expect, and we will set you up.

A tracking code — the value you put in the ref parameter on every link you send us.
An API token for the search and feed endpoints.
Commission terms: a percentage of the order total, up to an agreed maximum per booking.

Your token is a bearer credential: anyone holding it can query as you. We store only a hash of it, so we cannot read it back to you — keep it somewhere safe, and tell us straight away if it leaks and we will replace it.

Authentication

Send your token on every feed and search request, either as an Authorization header carrying the raw token — with no Bearer prefix — or as an accessToken query parameter. The redirect endpoints are public and take no token.

Example

curl -H "Authorization: YOUR_TOKEN" \
  "https://air-viva.com/api/v2/data/routes.json"

Failures

Both answer HTTP 401 with the code ERROR_UNAUTHORIZED:

No token at all: Authentication required
A token we do not recognise, or one belonging to a deactivated account: Access Denied [1]

Endpoints

Responses are JSON. Dates are ISO 8601 (YYYY-MM-DD). Airports are referenced either by IATA code or by the numeric id from the airports feed; both are accepted everywhere an airport is named.

GET/api/v2/data/airports.jsonToken required

Every airport we serve, with its numeric id, IATA code, city and country.

Static reference data. Cache it — it changes rarely, and the ids are stable.

GET/api/v2/data/routes.jsonToken required

The airport pairs we actually fly, as departure and destination pairs.

Two airports we serve do not make a bookable pair. Use this feed to confine your searches to routes that exist — a pair outside it can only ever answer empty.

GET/api/v2/data/routes/with-availability.jsonToken required

The same pairs, with the days each route operates.

Use this to avoid searching a route on a day it does not fly.

GET/api/v2/flights.jsonToken required

Search one route on one date, one way or return.

Answers an object with departure and return arrays. Each flight carries its own id — pass that id to the redirect endpoint to land the traveller on it.

Parameters

from required: Origin airport, IATA code or id.
to required: Destination airport, IATA code or id.
departureDate required: Outbound date, YYYY-MM-DD.
returnDate optional: Return date for a round trip. Omit for one way.
adults optional: Adult passengers. Defaults to 1.
children optional: Child passengers. Defaults to 0.
infants optional: Infants on lap. Defaults to 0.

A pair we do not fly answers empty arrays, not an error — an empty answer is never a reason to retry.
A date in the past answers empty rather than failing.

GET/api/v2/redirectPublic

The deep link. Send travellers here to land on the flight they clicked.

Redirects to our results page with the trip already filled in, and records your attribution. This endpoint never errors: an id we cannot resolve still lands the traveller on a usable page rather than a dead end.

Parameters

flightId required: The outbound flight id from a search response.
returnFlightId optional: The inbound flight id, for a round trip.
ref required: Your tracking code. Without it the visit earns you nothing.
subAffiliate optional: Your own sub-channel label, returned to you in reporting.
campaign optional: Your own campaign label.
partnerClickId optional: Your click identifier, so you can reconcile a booking against your own logs.
currency optional: Currency to display prices in. Does not change the currency charged.

GET/api/v2/redirect-multiPublic

The deep link for a round trip, taking both legs as a list.

Reads flightIds as a collection: the first entry is the outbound, the second the inbound. Takes the same attribution parameters as the single redirect.

Parameters

flightIds[] required: Flight ids in order: outbound first, inbound second.
ref required: Your tracking code.

GET/api/v2/results-multiPublic

A deep link built from airports and dates rather than flight ids.

Use this when you have no flight id to hand — for example from a cached or expired search. Reads destinations as indexed parameters: destinations[0][from], destinations[0][to], destinations[0][date].

Parameters

destinations[N][from] required: Origin airport for leg N.
destinations[N][to] required: Destination airport for leg N.
destinations[N][date] required: Date for leg N.
ref required: Your tracking code.

A destination we cannot resolve is skipped rather than refused.

Attribution

Put your tracking code in the ref parameter on every link. We set a first-party cookie when the traveller lands, and read it back if they book — so a booking counts for you even when it happens days after the click.

https://air-viva.com/api/v2/redirect?flightId=1000000000123&ref=YOUR_CODE

The attribution window is 42 days from the click.
The most recent click wins: if a traveller arrives through another partner after you, the booking is theirs.
A booking is attributed once, at the moment it is created.

Commission

You earn an agreed percentage of the order total, up to an agreed maximum per booking. The exact numbers are in your own agreement — the rules below apply to everyone.

The maximum is per booking, not per passenger: one booking earns one capped commission however many travellers are on it.
Commission is calculated on the order total actually charged, not on a price quoted earlier.
Amounts are rounded down to the cent.
Commission is earned on bookings that are paid for. A held or abandoned checkout earns nothing.
A booking sold in a currency other than your payout currency is reported to you rather than paid automatically — we do not convert at settlement, we agree the rate with you.

Reporting

We are rebuilding partner reporting alongside the new platform. Until it ships, ask us for your statement and we will send it — including everything needed for an invoice.

Fair use

We buy our inventory from airlines under contracts that measure how many searches we send them per booking. That budget is shared with you, so a few habits keep the connection healthy for both of us.

Search only pairs in the routes feed, on days the availability feed says they operate. A pair we do not fly can only answer empty, and asking anyway spends the budget for nothing.
Cache the airport and route feeds. They change rarely.
Do not poll a search repeatedly for the same trip. Prices are held at booking, not at search.
Tell us before you materially increase your query volume, so we can raise our own limits first.

Questions

Something unclear, something broken, or an endpoint you need that is not here? Get in touch — we would rather change the API than have you work around it.