Getting Started

This guide will get you making your first API call in under 5 minutes.

Prerequisites

• An API token issued by Flywire for your agency
• A tool for making HTTP requests: curl, Python with requests, or Node.js with fetch

Environments

Environment	Base URL
Production	https://api-platform.flywire.com/agents/v2/
Demo	https://api-platform.demo.flywire.com/agents/v2/

WARNING

Use the demo environment for testing and development. All examples in this documentation default to the demo environment.

Your First Request

Start by hitting the API root. This is the only URL you need to know — everything else is discovered from here.

curl

curl 'https://api-platform.demo.flywire.com/agents/v2/' \
  --header 'X-Authentication-Key: YOUR_API_TOKEN'

Python

import requests

BASE_URL = "https://api-platform.demo.flywire.com/agents/v2/"
TOKEN = "YOUR_API_TOKEN"

response = requests.get(
    BASE_URL,
    headers={"X-Authentication-Key": TOKEN}
)
root = response.json()
print(root)

Node.js

const BASE_URL = "https://api-platform.demo.flywire.com/agents/v2/";
const TOKEN = "YOUR_API_TOKEN";

const response = await fetch(BASE_URL, {
  headers: { "X-Authentication-Key": TOKEN }
});
const root = await response.json();
console.log(root);

Response

HTTP/1.1 200 OK
Content-Type: application/json
Link: <tag:flywire.com,2016:agents:api:profile:hypermedia>;rel="profile"

{
  "links": [
    {
      "rel": "self",
      "href": "https://api-platform.demo.flywire.com/agents/v2/"
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:intermediated-payments",
      "href": "..."
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:claim-intermediation-of-payment",
      "href": "..."
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:payment-recipients",
      "href": "..."
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:insurance-types",
      "href": "..."
    },
    {
      "rel": "tag:flywire.com,2016:agents:api:relation:intermediated-insurance-applications",
      "href": "..."
    }
  ]
}

Understanding the Response

Through the hypermedia profile, the root response exposes a links array with the available next steps. For example, the response above gives you:

Relation	What it does
intermediated-payments	Browse all payments intermediated by your agency
claim-intermediation-of-payment	Claim an existing payment as intermediated by your agency
payment-recipients	Discover payment recipients and create payment experiences
insurance-types	Start the insurance application process
intermediated-insurance-applications	Browse all insurance applications intermediated by your agency

Navigating the API

To continue, pick a relation and follow its href. If you would like to start the process of applying for insurance, this is what you would do:

curl

# Extract the href for insurance-types from the root response, then GET it
curl 'THE_HREF_FROM_RESPONSE' \
  --header 'X-Authentication-Key: YOUR_API_TOKEN'

Python

# Find the link with the insurance-types relation
insurance_link = next(
    link for link in root["links"]
    if link["rel"].endswith("insurance-types")
)

# Follow it
response = requests.get(
    insurance_link["href"],
    headers={"X-Authentication-Key": TOKEN}
)
types = response.json()

Node.js

// Find the link with the insurance-types relation
const insuranceLink = root.links.find(
  link => link.rel.endsWith("insurance-types")
);

// Follow it
const typesResponse = await fetch(insuranceLink.href, {
  headers: { "X-Authentication-Key": TOKEN }
});
const types = await typesResponse.json();

The Golden Rule

Never hardcode URLs. Always discover them by following links from responses. This makes your integration resilient to API changes.

Next Steps

• Learn the Core Concepts behind the API
• Look up any link, response shape, or status enum in the Reference section
• Follow the Create a Payment Experience guide
• Follow the Purchase OSHC Insurance guide
• Run the interactive guide applications against the demo environment