Agents API Docs

Appearance

Purchase OSHC Insurance ​

This guide walks through the complete flow for purchasing Overseas Student Health Cover (OSHC) — from browsing insurance types to generating a payment link.

Step 1: Get Insurance Types ​

Fetch the root, then follow insurance-types. The response lists types with anchored request-insurance-quote links:

bash
curl 'https://api-platform.demo.flywire.com/agents/v2/' -H 'X-Authentication-Key: YOUR_API_TOKEN'
# Follow the insurance-types href from the response
curl 'https://api-platform.demo.flywire.com/agents/v2/insurance-types' -H 'X-Authentication-Key: YOUR_API_TOKEN'
python
import requests
HEADERS = {"X-Authentication-Key": "YOUR_API_TOKEN"}
root = requests.get("https://api-platform.demo.flywire.com/agents/v2/", headers=HEADERS).json()
types_link = next(l for l in root["links"] if l["rel"].endswith("insurance-types"))
types = requests.get(types_link["href"], headers=HEADERS).json()
javascript
const HEADERS = { "X-Authentication-Key": "YOUR_API_TOKEN" };
const root = await fetch("https://api-platform.demo.flywire.com/agents/v2/", { headers: HEADERS }).then(r => r.json());
const typesLink = root.links.find(l => l.rel.endsWith("insurance-types"));
const types = await fetch(typesLink.href, { headers: HEADERS }).then(r => r.json());
json
{
  "items": [{ "name": "NZ" }, { "name": "OSHC" }, { "name": "OVHC" }],
  "links": [
    { "rel": "...request-insurance-quote", "href": ".../insurance-quote-request?data=eyJ0eXBlIjoiTloiLCJkZWZhdWx0cyI6e30sImV4dHJhcyI6W119...", "anchor": "#/items/0" },
    { "rel": "...request-insurance-quote", "href": ".../insurance-quote-request?data=eyJ0eXBlIjoiT1NIQyIsImRlZmF1bHRzIjp7fSwiZXh0cmFzIjpbXX0...", "anchor": "#/items/1" },
    { "rel": "...request-insurance-quote", "href": ".../insurance-quote-request?data=eyJ0eXBlIjoiT1ZIQyIsImRlZmF1bHRzIjp7fSwiZXh0cmFzIjpbXX0...", "anchor": "#/items/2" }
  ]
}

Links are opaque

The request-insurance-quote href is always /insurance-quote-request?data=<signed token> regardless of which insurance type the anchor points to — the type and any defaults are packed into the signed data payload, not the URL path. Treat the href as opaque: follow it, don't construct it.

Step 2: Get the Quote Form and Submit ​

Follow request-insurance-quote anchored to #/items/1 (OSHC). A GET returns the form schema with fields adults, children, policy_start_date, policy_end_date. POST your data and follow the 303 redirect to /insurance-quotes?data=... to see the offers:

bash
# OSHC_QUOTE_HREF is the href of the link with anchor #/items/1 from the response above
curl -X POST "$OSHC_QUOTE_HREF" \
  -H 'X-Authentication-Key: YOUR_API_TOKEN' -H 'Content-Type: application/json' \
  -d '{"adults":1,"children":0,"policy_start_date":"2026-07-01","policy_end_date":"2027-06-30"}' -L
python
oshc_link = next(l for l in types["links"] if l["rel"].endswith("request-insurance-quote") and l.get("anchor") == "#/items/1")
quotes = requests.post(oshc_link["href"], headers=HEADERS, json={
    "adults": 1, "children": 0, "policy_start_date": "2026-07-01", "policy_end_date": "2027-06-30"
}, allow_redirects=True).json()
javascript
const oshcLink = types.links.find(l => l.rel.endsWith("request-insurance-quote") && l.anchor === "#/items/1");
const quotes = await fetch(oshcLink.href, {
  method: "POST", headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({ adults: 1, children: 0, policy_start_date: "2026-07-01", policy_end_date: "2027-06-30" }),
  redirect: "follow"
}).then(r => r.json());

Step 3: Review Quotes ​

The response contains features (comparison columns) and offers (one per provider). Each offer has an anchored apply-for-insurance link. See Compare Insurance Quotes for details.

Example quotes response
json
{
  "features": [
    { "key": "hospital", "label": "Hospital Cover" },
    { "key": "extras", "label": "Extras Cover" }
  ],
  "offers": [
    {
      "category": "OSHC", "provider": "Bupa", "product": "Basic OSHC",
      "price": { "value": 692.00, "currency": "AUD" },
      "features": { "hospital": "Included", "extras": "Not included" }
    },
    {
      "category": "OSHC", "provider": "Allianz", "product": "Standard OSHC",
      "price": { "value": 748.50, "currency": "AUD" },
      "features": { "hospital": "Included", "extras": "Basic extras" }
    }
  ],
  "links": [
    { "rel": "...adjust-insurance-quote", "href": "..." },
    { "rel": "...apply-for-insurance", "href": "...", "anchor": "#/offers/0" },
    { "rel": "...apply-for-insurance", "href": "...", "anchor": "#/offers/1" }
  ]
}

Step 4: Apply for Insurance ​

Follow apply-for-insurance for Bupa Basic OSHC (#/offers/0) to get the application form. Fill in personal details and POST:

bash
curl -X POST 'THE_APPLY_HREF' -H 'X-Authentication-Key: YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' -d '{"title":"Mr","given_name":"John","surname":"Smith",
  "date_of_birth":"1998-03-15","gender":"male","mobile":"+61412345678",
  "email":"[email protected]","home_country":"GB","passport_number":"P12345678",
  "education_institution":"University of Sydney",
  "visa_details":{"visa_type":"Student","visa_sub_class":"500"},"terms_accepted":true}' -L
python
apply_link = next(l for l in quotes["links"] if l["rel"].endswith("apply-for-insurance") and l.get("anchor") == "#/offers/0")
application = requests.post(apply_link["href"], headers=HEADERS, json={
    "title": "Mr", "given_name": "John", "surname": "Smith", "date_of_birth": "1998-03-15",
    "gender": "male", "mobile": "+61412345678", "email": "[email protected]",
    "home_country": "GB", "passport_number": "P12345678",
    "education_institution": "University of Sydney",
    "visa_details": {"visa_type": "Student", "visa_sub_class": "500"}, "terms_accepted": True
}, allow_redirects=True).json()
javascript
const applyLink = quotes.links.find(l => l.rel.endsWith("apply-for-insurance") && l.anchor === "#/offers/0");
const application = await fetch(applyLink.href, {
  method: "POST", headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Mr", given_name: "John", surname: "Smith", date_of_birth: "1998-03-15",
    gender: "male", mobile: "+61412345678", email: "[email protected]",
    home_country: "GB", passport_number: "P12345678",
    education_institution: "University of Sydney",
    visa_details: { visa_type: "Student", visa_sub_class: "500" }, terms_accepted: true
  }), redirect: "follow"
}).then(r => r.json());

The 303 redirect leads to the application details:

json
{
  "policy": { "reference": "INS-2026-00042981" },
  "status": { "current": { "name": "unpaid" } },
  "price": { "value": 692.00, "currency": "AUD" },
  "information": {
    "value": { "given_name": "John", "surname": "Smith", "education_institution": "University of Sydney",
      "provider": "Bupa", "product": "Basic OSHC" },
    "schema": { "type": "object", "properties": { "...": "..." } }
  },
  "intermediation": {
    "timestamp": "2026-03-23T10:30:00Z",
    "agent": { "name": "Your Agency" }, "client": { "name": "John Smith" }
  },
  "links": [{ "rel": "...standard-payment-experience", "href": "..." }]
}

POST to standard-payment-experience to generate a payment experience. Share the payment link with your client.

bash
curl -X POST 'THE_PAYMENT_EXPERIENCE_HREF' -H 'X-Authentication-Key: YOUR_API_TOKEN' -L
python
pay_link = next(l for l in application["links"] if l["rel"].endswith("standard-payment-experience"))
payment = requests.post(pay_link["href"], headers=HEADERS, allow_redirects=True).json()
pay_url = next(l for l in payment["links"] if l["rel"].endswith("payment"))
print(f"Send this link to your client: {pay_url['href']}")
javascript
const payLink = application.links.find(l => l.rel.endsWith("standard-payment-experience"));
const payment = await fetch(payLink.href, { method: "POST", headers: HEADERS, redirect: "follow" }).then(r => r.json());
const payUrl = payment.links.find(l => l.rel.endsWith("payment"));
console.log(`Send this link to your client: ${payUrl.href}`);

WARNING

The payment link is single-use. If the client abandons the payment, generate a new one.

What's Next ​

Flywire Agents API Documentation

© 2026 Flywire