Manage Insurance Policies

This guide covers browsing intermediated insurance applications, checking policy status, and performing lifecycle actions — paying, downloading certificates, extending, and cancelling.

Browsing Applications

Follow the intermediated-insurance-applications link from the root.

curl

curl 'https://api-platform.demo.flywire.com/agents/v2/intermediated-insurance-applications' \
  -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()
apps_link = next(l for l in root["links"] if l["rel"].endswith("intermediated-insurance-applications"))
apps = requests.get(apps_link["href"], headers=HEADERS).json()

Node.js

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 appsLink = root.links.find(l => l.rel.endsWith("intermediated-insurance-applications"));
const apps = await fetch(appsLink.href, { headers: HEADERS }).then(r => r.json());

Response

Each item includes policy reference, status, price, and intermediation details. Items have anchored links — intermediated-insurance-application for the detail page, plus standard-payment-experience if unpaid.

{
  "items": [
    {
      "policy": { "reference": "INS-2026-00042981" }, "status": { "name": "unpaid" },
      "price": { "value": 692.00, "currency": "AUD" },
      "intermediation": { "timestamp": "2026-03-23T10:30:00Z",
        "agent": { "name": "Your Agency" }, "client": { "name": "John Smith" } }
    },
    {
      "policy": { "reference": "INS-2026-00042855" }, "status": { "name": "paid" },
      "price": { "value": 1250.00, "currency": "AUD" },
      "intermediation": { "timestamp": "2026-03-20T14:15:00Z",
        "agent": { "name": "Your Agency" }, "client": { "name": "Jane Doe" } }
    }
  ],
  "links": [
    { "rel": "...intermediated-insurance-application", "href": "...INS-2026-00042981", "anchor": "#/items/0" },
    { "rel": "...standard-payment-experience", "href": "...INS-2026-00042981/pay", "anchor": "#/items/0" },
    { "rel": "...intermediated-insurance-application", "href": "...INS-2026-00042855", "anchor": "#/items/1" },
    { "rel": "...certificate-of-insurance", "href": "...", "anchor": "#/items/1/policy" },
    { "rel": "first", "href": "...?page=1" },
    { "rel": "next", "href": "...?page=2" },
    { "rel": "last", "href": "...?page=3" }
  ]
}

Policy-lifecycle actions on a list item (e.g. certificate-of-insurance on the paid second application above) carry a nested anchor #/items/N/policy — they target the policy sub-object of item N, not the item itself. See Anchoring for the pattern. Navigate between pages using first, prev, next, and last links.

Application Details

Follow intermediated-insurance-application for a specific item to get the full detail including information (value + schema):

{
  "policy": { "reference": "INS-2026-00042855" },
  "status": { "current": { "name": "paid", "timestamp": "2026-03-21T08:00:00Z" } },
  "price": { "value": 1250.00, "currency": "AUD" },
  "information": {
    "value": { "given_name": "Jane", "surname": "Doe",
      "education_institution": "University of Melbourne",
      "provider": "Allianz", "product": "Standard OSHC" },
    "schema": { "type": "object", "properties": { "...": "..." } }
  },
  "intermediation": { "timestamp": "2026-03-20T14:15:00Z",
    "agent": { "name": "Your Agency" }, "client": { "name": "Jane Doe" } },
  "links": [
    { "rel": "...certificate-of-insurance", "href": "...", "anchor": "#/policy" },
    { "rel": "...extend-insurance-policy", "href": "...", "anchor": "#/policy" },
    { "rel": "...cancel-insurance-policy", "href": "...", "anchor": "#/policy" }
  ]
}

The three policy actions carry anchor: "#/policy" — they apply to the policy sub-object on the body, not to the application as a whole. The same actions on a list item use #/items/N/policy (the nested-anchor pattern shown in the response above). See Anchoring.

Status shape differs between list and detail

List items expose status.name (a direct string). The detail view nests it as status.current.name — see Status: list vs detail for the rationale.

Actions by Status

Status	Available Actions
unpaid	standard-payment-experience — create a payment link
paid	certificate-of-insurance, extend-insurance-policy, cancel-insurance-policy
cancelled	No actions available
expired	No actions available

paid is the "active policy" state — once payment has been received, the policy-lifecycle actions become available on the resource. The other status values are reported but never carry actions.

Create a Payment Link (unpaid)

POST to standard-payment-experience. Share the returned payment link with the client.

Download Certificate (paid)

GET the certificate-of-insurance link to download the policy certificate as a PDF.

Extend a Policy (paid)

POST to extend-insurance-policy with the new end date:

{ "policy_end_date": "2028-06-30" }

Cancel a Policy (paid)

POST to cancel-insurance-policy. The status changes to cancelled.

WARNING

Cancellation may not be reversible. Confirm with the client before cancelling.

Code examples for all actions

# Payment link
pay_link = next(l for l in app["links"] if l["rel"].endswith("standard-payment-experience"))
payment = requests.post(pay_link["href"], headers=HEADERS, allow_redirects=True).json()

# Certificate
cert_link = next(l for l in app["links"] if l["rel"].endswith("certificate-of-insurance"))
cert = requests.get(cert_link["href"], headers=HEADERS)
with open("certificate.pdf", "wb") as f:
    f.write(cert.content)

# Extend
ext_link = next(l for l in app["links"] if l["rel"].endswith("extend-insurance-policy"))
extended = requests.post(ext_link["href"], headers=HEADERS,
    json={"policy_end_date": "2028-06-30"}, allow_redirects=True).json()

# Cancel
cancel_link = next(l for l in app["links"] if l["rel"].endswith("cancel-insurance-policy"))
cancelled = requests.post(cancel_link["href"], headers=HEADERS, allow_redirects=True).json()

Related

• Purchase OSHC Insurance — full purchase flow from quote to payment
• Compare Insurance Quotes — understanding quote features and offers
• Insurance Schemas — JSON schemas for applications and statuses