Common Profiles

Structural profiles describe the general shape of a response body, regardless of domain. They are shared between the Payments API and the Insurance API. Each profile URI is the full tag tag:flywire.com,2016:agents:api:profile:{name} — the short name in the table is the suffix after the colon.

Structural profiles are usually combined with one or more domain profiles that further refine what the response represents.

Profile	Description
hypermedia	Representations advertising this profile comply with the hypermedia schema — i.e. they expose a links array.
root	Representations advertising this profile will, when generated along with the hypermedia profile, expose links to the main functionalities offered by the API: intermediated-payments, payment-recipients and claim-intermediation-of-payment for payments; insurance-types and intermediated-insurance-applications for insurance.
item	Representations advertising this profile will, when generated along with the hypermedia 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.
form	Representations advertising this profile comply with the form schema. Their main purpose is to define a schema which can then be used to collect data from a user.

Reading profiles in code

Profiles are delivered as Link headers with rel="profile". A single response often advertises several at once — typically a structural profile plus one or more domain profiles. To pick a code path based on the response shape, parse the Link header and match on the profile URI suffix:

Python

linkHeaders = response.headers.get("Link", "").split(",")
profiles = [
    h.split(";")[0].strip().strip("<>")
    for h in linkHeaders
    if 'rel="profile"' in h
]

is_collection = any(p.endswith(":item") for p in profiles)
is_form = any(p.endswith(":form") for p in profiles)

Node.js

const linkHeaders = (response.headers.get("link") ?? "").split(", ");
const profiles = linkHeaders
  .filter(h => h.includes('rel="profile"'))
  .map(h => h.match(/<(.+?)>/)?.[1]);

const isCollection = profiles.some(p => p.endsWith(":item"));
const isForm = profiles.some(p => p.endsWith(":form"));