Insurance Schemas

Domain JSON schemas defined by the Insurance API. Each entry pairs a human-readable layer (a field table and a representative example) with the verbatim JSON Schema advertised by the API. Schemas are identified by tags as defined in RFC 4151 — the full schema identifier is tag:flywire.com,2016:agents:api:schema:{name}.

Schemas shared with the Payments API (hypermedia, form, intermediation, dynamic-data, amount, iso-4217, iso-3166-1-alpha-2, timestamp) live in Common Schemas.

TIP

The JSON Schema block is the canonical definition. The tables and examples are there to make the JSON Schema readable — when in doubt, the JSON Schema block wins.

`insurance-types`

Returned when following the insurance-types link from the root. Each item carries just a name; the action available on each entry (request-insurance-quote) is exposed via anchored links in the enclosing hypermedia envelope.

json

{
  "items": [{ "name": "NZ" }, { "name": "OSHC" }, { "name": "OVHC" }],
  "links": [
    { "rel": "tag:flywire.com,2016:agents:api:relation:request-insurance-quote", "href": "...", "anchor": "#/items/0" },
    { "rel": "tag:flywire.com,2016:agents:api:relation:request-insurance-quote", "href": "...", "anchor": "#/items/1" },
    { "rel": "tag:flywire.com,2016:agents:api:relation:request-insurance-quote", "href": "...", "anchor": "#/items/2" }
  ]
}

Field	Type	Description
`items[].name`	`string`	Insurance type identifier: `NZ`, `OSHC`, or `OVHC`
`links[]`	`Link[]`	Anchored `request-insurance-quote` links, one per type

JSON Schema — tag:flywire.com,2016:agents:api:schema:insurance-types

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:insurance-types",
  "type": "array",
  "items": {
    "type": "object",
    "properties": { "name": { "type": "string" } },
    "required": ["name"]
  }
}

`insurance-quote`

Returned after submitting a quote request (POST → 303 redirect). Carries:

features[] — column headers used by offers[].features, optionally with a breakdown of help text entries
offers[] — one entry per offered policy, with the offer's price and a per-feature value/hint map

json

{
  "features": [
    {
      "key": "visa_compliance",
      "label": "Visa Compliance",
      "breakdown": [
        { "key": "meets_govt_requirements", "label": "Meets government requirements", "help": "These policies will fulfil your international student visa requirements." }
      ]
    }
  ],
  "offers": [
    {
      "category": "single",
      "provider": "Bupa",
      "product": "Basic",
      "price": { "value": 692.00, "currency": "AUD" },
      "features": {
        "visa_compliance": { "text": "Compliant", "hint": "green-tick" }
      }
    }
  ],
  "links": [
    { "rel": "tag:flywire.com,2016:agents:api:relation:apply-for-insurance", "href": "...", "anchor": "#/offers/0" }
  ]
}

Field	Type	Description
`features[].key`	`string`	Lookup key used in each offer's `features` map
`features[].label`	`string`	Human-readable column header
`features[].breakdown[]`	`object[]?`	Optional help text entries with `key`, `label`, and `help`
`offers[].category`	`string`	Offer category (e.g. `single`, `couple`, `family`)
`offers[].provider`	`string`	Insurance provider name
`offers[].product`	`string`	Product name
`offers[].price`	`amount`	Price for the quoted period
`offers[].features`	`object`	Map of feature `key` → `{ text?, hint? }`

JSON Schema — tag:flywire.com,2016:agents:api:schema:insurance-quote

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:insurance-quote",
  "type": "object",
  "properties": {
    "features": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": { "type": "string" },
          "label": { "type": "string" },
          "breakdown": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string" },
                "label": { "type": "string" },
                "help": { "type": "string" }
              },
              "required": ["key", "label"]
            }
          }
        },
        "required": ["key", "label", "breakdown"]
      }
    },
    "offers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "category": { "type": "string" },
          "provider": { "type": "string" },
          "product": { "type": "string" },
          "price": { "$ref": "tag:flywire.com,2016:agents:api:schema:amount" },
          "features": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "text": { "type": "string" },
                "hint": { "type": "string" }
              }
            }
          }
        },
        "required": ["category", "provider", "product", "price", "features"]
      }
    }
  },
  "required": ["features", "offers"]
}

`intermediated-insurance-applications`

The collection wrapper returned when following the intermediated-insurance-applications relation. It carries an items array whose elements conform to intermediated-insurance-application-summary.

json

{
  "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" }
      }
    }
  ],
  "links": [
    { "rel": "self", "href": "..." }
  ]
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:intermediated-insurance-applications

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:intermediated-insurance-applications",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "tag:flywire.com,2016:agents:api:schema:intermediated-insurance-application-summary"
      }
    }
  },
  "required": ["items"]
}

`intermediated-insurance-application-summary`

A single row in the intermediated insurance applications list.

Field	Type	Description
`policy.reference`	`string`	Unique policy reference (e.g. `INS-2026-00042981`)
`status.name`	`insurance-application-status-name`	Current status
`price`	`amount`	Total policy price
`intermediation`	`intermediation`	Who intermediated this application and when

json

{
  "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" }
  }
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:intermediated-insurance-application-summary

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:intermediated-insurance-application-summary",
  "type": "object",
  "properties": {
    "policy": {
      "type": "object",
      "properties": { "reference": { "type": "string" } },
      "required": ["reference"]
    },
    "status": {
      "type": "object",
      "properties": {
        "name": { "$ref": "tag:flywire.com,2016:agents:api:schema:insurance-application-status-name" }
      },
      "required": ["name"]
    },
    "price": { "$ref": "tag:flywire.com,2016:agents:api:schema:amount" },
    "intermediation": { "$ref": "tag:flywire.com,2016:agents:api:schema:intermediation" }
  },
  "required": ["reference", "recipient", "status", "price", "intermediation"]
}

Spec quirk

The published schema's required[] list ends with ["reference", "recipient", "status", "price", "intermediation"], but reference and recipient are not defined in this schema's properties{} (reference lives under policy.reference; recipient is not present on summaries at all). The block above reproduces the schema verbatim; treat policy.reference, status, price, and intermediation as the effective required fields.

:::

Status: list vs detail

The list and detail responses expose the same status value in two different shapes:

Surface	Shape	Access
List (`intermediated-insurance-application-summary`)	`"status": { "name": "unpaid" }`	`status.name`
Detail (`intermediated-insurance-application`)	`"status": { "current": { "name": "unpaid", "timestamp": "..." } }`	`status.current.name`

The detail view nests the value inside current so the resource can carry the timestamp at which the status was reached (and grow further fields later) without breaking clients that already read status.current.name. Clients consuming both surfaces should branch on which one they're parsing.

`intermediated-insurance-application`

Returned when following an intermediated-insurance-application link, or after submitting an application. Carries the policy reference, the nested current status, the price, the application's information payload (with its schema), and the intermediation block.

When generated together with the hypermedia profile, the body advertises the IANA payment link until the application is considered complete.

Field	Type	Description
`policy.reference`	`string`	Unique policy reference
`status.current.name`	`insurance-application-status-name`	Current status (see Status: list vs detail)
`price`	`amount`	Total policy price
`information`	`dynamic-data`	Application data with its schema
`intermediation`	`intermediation`	Intermediation details
`links[]`	`Link[]`	Available actions depending on status. Policy actions are anchored to `#/policy` — see Anchoring

json

{
  "policy": { "reference": "INS-2026-00042981" },
  "status": { "current": { "name": "unpaid", "timestamp": "2026-03-23T10:30:00Z" } },
  "price": { "value": 692.00, "currency": "AUD" },
  "information": {
    "value": { "given_name": "John", "surname": "Smith", "provider": "Bupa" },
    "schema": {
      "type": "object",
      "properties": {
        "given_name": { "type": "string", "title": "Given Name" },
        "surname": { "type": "string", "title": "Surname" }
      }
    }
  },
  "intermediation": {
    "timestamp": "2026-03-23T10:30:00Z",
    "agent": { "name": "Your Agency" },
    "client": { "name": "John Smith" }
  },
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "payment", "href": "..." },
    { "rel": "tag:flywire.com,2016:agents:api:relation:certificate-of-insurance", "href": "...", "anchor": "#/policy" },
    { "rel": "tag:flywire.com,2016:agents:api:relation:extend-insurance-policy", "href": "...", "anchor": "#/policy" },
    { "rel": "tag:flywire.com,2016:agents:api:relation:cancel-insurance-policy", "href": "...", "anchor": "#/policy" }
  ]
}

JSON Schema — tag:flywire.com,2016:agents:api:schema:intermediated-insurance-application

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:intermediated-insurance-application",
  "type": "object",
  "$defs": {
    "status": {
      "type": "object",
      "properties": {
        "name": { "$ref": "tag:flywire.com,2016:agents:api:schema:insurance-application-status-name" },
        "timestamp": { "$ref": "tag:flywire.com,2016:agents:api:schema:timestamp" }
      },
      "required": ["name", "timestamp"]
    }
  },
  "properties": {
    "policy": {
      "type": "object",
      "properties": { "reference": { "type": "string" } },
      "required": ["reference"]
    },
    "status": {
      "type": "object",
      "properties": { "current": { "$ref": "#/$defs/status" } },
      "required": ["current"]
    },
    "price": { "$ref": "tag:flywire.com,2016:agents:api:schema:amount" },
    "information": { "$ref": "tag:flywire.com,2016:agents:api:schema:dynamic-data" },
    "intermediation": { "$ref": "tag:flywire.com,2016:agents:api:schema:intermediation" }
  },
  "required": ["reference", "recipient", "status", "price", "information", "intermediation"]
}

Spec quirk

The published schema carries the intermediated-insurance-application-summary $id on this detail schema and repeats the same suspect required[] list (["reference", "recipient", "status", "price", "information", "intermediation"]) — see the summary section above. Effective required fields are policy.reference, status.current, price, information, intermediation.

:::

`insurance-application-status-name`

The enum of valid status names for an insurance application.

Value	Description	Drives actions?
`unpaid`	Application submitted but payment not yet completed	✓ — `payment` link exposed via `intermediated-insurance-application` profile
`paid`	Payment received, policy is active	✓ — `certificate-of-insurance`, `extend-insurance-policy`, `cancel-insurance-policy`
`cancelled`	Policy has been cancelled	✗
`expired`	Policy coverage period has ended	✗

JSON Schema — tag:flywire.com,2016:agents:api:schema:insurance-application-status-name

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:flywire.com,2016:agents:api:schema:insurance-application-status-name",
  "type": "string",
  "enum": ["unpaid", "paid", "cancelled", "expired"]
}

Insurance Schemas ​

insurance-types ​

insurance-quote ​

intermediated-insurance-applications ​

intermediated-insurance-application-summary ​

Status: list vs detail ​

intermediated-insurance-application ​

insurance-application-status-name ​

Insurance Schemas

`insurance-types`

`insurance-quote`

`intermediated-insurance-applications`

`intermediated-insurance-application-summary`

Status: list vs detail

`intermediated-insurance-application`

`insurance-application-status-name`