Link Relations

Every link in the API carries a relation type (rel) that tells you how the target resource is related to the current one. You use relation types — not URL patterns — to find the link you need.

How relation types are identified

Outside of the IANA-registered link relation types (which, unless otherwise stated, maintain the semantics defined in the registry), the API also defines its own relation types to aid navigation. They are identified by tags as defined in RFC 4151 and are, as such, URIs:

tag:flywire.com,2016:agents:api:relation:{name}

When matching links in code, you compare the rel against the full tag URI — never against the short suffix in isolation.

Using relations

When encountering the hypermedia profile's links, you can expose them as actions in your UIs. If you're interacting with the API in a server-to-server scenario, your client will have to pick and execute the action itself, based on what is required next. You can do that by finding the href of the link with the relation you're interested in and following it (or whatever the relation calls for):

Python

RELATION = "tag:flywire.com,2016:agents:api:relation:"

def find_link(response_json, relation):
    return next(
        link for link in response_json["links"]
        if link["rel"] == f"{RELATION}{relation}"
        and "anchor" not in link
    )

insurance_link = find_link(root, "insurance-types")
response = requests.get(insurance_link["href"], headers=auth)

Node.js

const RELATION = "tag:flywire.com,2016:agents:api:relation:";

function findLink(body, relation) {
  return body.links.find(
    link => link.rel === `${RELATION}${relation}` && !link.anchor
  );
}

const insuranceLink = findLink(root, "insurance-types");
const response = await fetch(insuranceLink.href, { headers: auth });

TIP

When filtering links, also check for the absence of anchor if you want the link that applies to the resource itself rather than a specific part of it. See Anchoring.

Designed for end-user UIs

Not all relation types are designed for server-to-server communication. Some link relations — for example the payment IANA relation, or monitor, certificate-of-insurance, payment-receipt — point to user-facing pages or downloadable documents and are intended to be opened by the end user, not fetched programmatically.

State-dependent links

The set of links present in a response depends on the state of the resource and your agency's permissions. For example, cancel-insurance-policy only appears for policies that are active and eligible for cancellation. Never assume a link will be present — always check before acting on it.

Reference

The full list of relation types defined by the API lives in the Reference section:

• Common Relations — IANA-registered relations (self, first, prev, next, last, payment, …) and shared extension relations
• Payments Relations — extension relations specific to the Payments API
• Insurance Relations — extension relations specific to the Insurance API