Pagination

Representations advertising the item profile expose links with the IANA-registered first, prev, next and last relation types — allowing clients to navigate to (if available) the first, previous, next and last items of the underlying collection.

Pagination Links

Relation	Meaning
first	First item (page) of the underlying collection
prev	Previous item (page) relative to the current one
next	Next item (page) relative to the current one
last	Last item (page) of the underlying collection

Only the links that make sense are included. On the first page there's no prev or first; on the last page there's no next or last.

Treat pagination URLs as opaque

Different collections use different pagination strategies (signed cursor tokens for payments, page indexes for insurance applications). Clients never need to know which — follow the href of the next/prev/first/last link as-is. Don't construct or modify these URLs yourself.

Example Response

A request to the intermediated payments collection might return:

{
  "items": [
    {
      "reference": "PAY-ABC123",
      "amount": { "value": 15000, "currency": "AUD" },
      "status": { "name": "delivered" },
      "recipient": { "name": "Demo University" },
      "intermediation": {
        "agent": { "name": "Acme Agency" },
        "client": { "name": "Wei Zhang" }
      }
    },
    {
      "reference": "PAY-DEF456",
      "amount": { "value": 8500, "currency": "AUD" },
      "status": { "name": "initiated" },
      "recipient": { "name": "Demo University" },
      "intermediation": {
        "agent": { "name": "Acme Agency" },
        "client": { "name": "Priya Sharma" }
      }
    }
  ],
  "links": [
    { "rel": "self", "href": "https://api-platform.demo.flywire.com/agents/v2/intermediated-payments?cursor=eyJ..." },
    { "rel": "next", "href": "https://api-platform.demo.flywire.com/agents/v2/intermediated-payments?cursor=eyJu..." },
    { "rel": "last", "href": "https://api-platform.demo.flywire.com/agents/v2/intermediated-payments?cursor=eyJs..." },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:intermediated-payment",
      "href": "https://...",
      "anchor": "#/items/0"
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:intermediated-payment",
      "href": "https://...",
      "anchor": "#/items/1"
    }
  ]
}

For the insurance applications collection the item shape is different — see Insurance Schemas — but the next/prev/first/last links work identically.

Iterating Through All Pages

To process every item in a collection, follow the next link until it's no longer present:

Python

def fetch_all_items(start_url, headers):
    url = start_url
    all_items = []

    while url:
        response = requests.get(url, headers=headers).json()
        all_items.extend(response.get("items", []))

        next_link = next(
            (link for link in response["links"] if link["rel"] == "next"),
            None
        )
        url = next_link["href"] if next_link else None

    return all_items

Node.js

async function fetchAllItems(startUrl, headers) {
  let url = startUrl;
  const allItems = [];

  while (url) {
    const response = await fetch(url, { headers });
    const body = await response.json();
    allItems.push(...(body.items ?? []));

    const nextLink = body.links.find(link => link.rel === "next");
    url = nextLink?.href ?? null;
  }

  return allItems;
}

Page Flow

What Else Is in the Links?

Collection pages might also include anchored links for the items — links like intermediated-payment with an anchor pointing to the specific item. These let you navigate to the detail view of any item in the list.