Anchoring — Links for Collection Items

Some links might not apply to the response as a whole — they apply to a specific item within it. The API uses the anchor property with JSON Pointer syntax to express this.

How Anchoring Works

When a link has an anchor field, it points to a specific location in the response body:

{
  "items": [
    { "name": "OSHC" },
    { "name": "OVHC" }
  ],
  "links": [
    { "rel": "self", "href": "https://..." },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:request-insurance-quote",
      "href": "https://api-platform.demo.flywire.com/agents/v2/insurance-quote-request?data=eyJvc2hj...",
      "anchor": "#/items/0"
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:request-insurance-quote",
      "href": "https://api-platform.demo.flywire.com/agents/v2/insurance-quote-request?data=eyJvdmhj...",
      "anchor": "#/items/1"
    }
  ]
}

Here, two links share the same rel (request-insurance-quote), but they're for different items:

• #/items/0 → the link is for OSHC (first item)
• #/items/1 → the link is for OVHC (second item)

Reading the JSON Pointer

The anchor value is the JSON Pointer's URI Fragment Identifier Representation (in other words, a JSON Pointer prefixed by #). Parse it to locate the item:

Anchor	Meaning
#/items/0	First item in the items array
#/items/1	Second item in the items array
#/items/2	Third item, and so on
#/items/0/policy	The policy sub-object of the first item

Matching Links to Items

To find the links for a specific item, filter by the anchor that corresponds to its array index:

Python

def links_for_item(response_json, index):
    anchor = f"#/items/{index}"
    return [
        link for link in response_json["links"]
        if link.get("anchor") == anchor
    ]

types = response.json()
for i, item in enumerate(types["items"]):
    item_links = links_for_item(types, i)
    print(f"{item['name']}: {len(item_links)} action(s) available")

Node.js

function linksForItem(body, index) {
  const anchor = `#/items/${index}`;
  return body.links.filter(link => link.anchor === anchor);
}

const types = await response.json();
types.items.forEach((item, i) => {
  const itemLinks = linksForItem(types, i);
  console.log(`${item.name}: ${itemLinks.length} action(s) available`);
});

Real-World Example: Insurance Applications

The intermediated insurance applications collection uses anchoring extensively. Each item can have different available actions depending on its status:

{
  "items": [
    {
      "status": "policy_activated",
      "policy": { "provider": "Medibank", "end_date": "2027-05-31" }
    }
  ],
  "links": [
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:intermediated-insurance-application",
      "href": "https://...",
      "anchor": "#/items/0"
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:standard-payment-experience",
      "href": "https://...",
      "anchor": "#/items/0"
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:certificate-of-insurance",
      "href": "https://...",
      "anchor": "#/items/0/policy"
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:extend-insurance-policy",
      "href": "https://...",
      "anchor": "#/items/0/policy"
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:cancel-insurance-policy",
      "href": "https://...",
      "anchor": "#/items/0/policy"
    }
  ]
}

Notice that certificate-of-insurance, extend-insurance-policy, and cancel-insurance-policy are anchored to #/items/0/policy — the policy sub-object of the first item, not the application itself.

Distinguishing Collection-Level from Item-Level Links

Links without an anchor apply to the collection as a whole (like self, next, last). Links with an anchor apply to a specific item.

TIP

When searching for a link that applies to the response as a whole, always filter out links that have an anchor property. When looking for links for a specific item, match on the anchor value.

A note on JSON Pointer and application/json

The Agents API informally extends application/json to allow JSON Pointer values (as defined in Section 6 of RFC 6901) inside the anchor field of a link. While using JSON Pointer for this purpose is a breach of the JSON specification, it is one we considered too useful not to make.