Request examples in cURL, JavaScript and Python

Start with a read request

Use the gateway URL supplied for your environment, an access token, and an existing account reference. See Get access, Authenticate and Read balances. The examples below call GET /api/accounts/{accountRef}/balances to read settled balances; they do not submit a transaction.

Set QFP_BASE_URL, QFP_ACCESS_TOKEN and QFP_ACCOUNT_REF in your environment. Keep access tokens out of source control. These examples use the current API version, 1.0.0.

cURL

curl --fail-with-body --request GET \
  "${QFP_BASE_URL}/api/accounts/${QFP_ACCOUNT_REF}/balances" \
  --header "Authorization: Bearer ${QFP_ACCESS_TOKEN}" \
  --header "API-Version: 1.0.0" \
  --header "Accept: application/json"

JavaScript

This example uses Node.js's built-in fetch.

const baseUrl = process.env.QFP_BASE_URL.replace(/\/$/, '');
const accountRef = encodeURIComponent(process.env.QFP_ACCOUNT_REF);
const response = await fetch(`${baseUrl}/api/accounts/${accountRef}/balances`, {
  headers: {
    Authorization: `Bearer ${process.env.QFP_ACCESS_TOKEN}`,
    'API-Version': '1.0.0',
    Accept: 'application/json',
  },
  signal: AbortSignal.timeout(30_000),
});
const body = await response.json();
if (!response.ok) {
  throw new Error(`QFP returned ${response.status}: ${body.message ?? response.statusText}`);
}
console.log(body);

Python

This example uses Python's standard library.

import json
import os
from urllib.parse import quote
from urllib.request import Request, urlopen
from urllib.error import HTTPError

base_url = os.environ['QFP_BASE_URL'].rstrip('/')
account_ref = quote(os.environ['QFP_ACCOUNT_REF'], safe='')
request = Request(
    f'{base_url}/api/accounts/{account_ref}/balances',
    headers={
        'Authorization': f"Bearer {os.environ['QFP_ACCESS_TOKEN']}",
        'API-Version': '1.0.0',
        'Accept': 'application/json',
    },
)
try:
    with urlopen(request, timeout=30) as response:
        print(json.load(response))
except HTTPError as error:
    body = json.loads(error.read())
    raise RuntimeError(f"QFP returned {error.code}: {body.get('message', error.reason)}") from error

Amounts in a successful balance response are decimal strings. Preserve their precision; see Amounts, currencies and precision. For authentication failures and other responses, see Errors.

Choose the method defined by the API

The API Reference contains the full request parameters, permissions, response schemas and generated samples for each endpoint. A method's meaning is endpoint-specific.

PUT example: replace a custom role's permissions

Use a sandbox custom role and a caller with role:update. Set QFP_TENANT_ID and QFP_ROLE_ID for that role. The tenant must match the caller's token. Newly granted permissions must be permissions the caller holds.

This operation replaces the permission set: omitted permissions are revoked. An empty array grants nothing. The following payload is the twoPermissions example from the generated API contract.

curl --fail-with-body --request PUT \
  "${QFP_BASE_URL}/api/tenants/${QFP_TENANT_ID}/roles/${QFP_ROLE_ID}/permissions" \
  --header "Authorization: Bearer ${QFP_ACCESS_TOKEN}" \
  --header "API-Version: 1.0.0" \
  --header "Content-Type: application/json" \
  --data '{"permissions":["policy:read","policy:approve"]}'

The endpoint returns 200 with the role's new permissions. A platform role cannot be edited. Invalid permissions, insufficient access and a missing role return the errors documented at PUT /api/tenants/{id}/roles/{roleId}/permissions.

Follow a write through to its outcome

For token operations, 202 Accepted means accepted, not settled. Keep the returned transaction identifier and follow GET /api/transactions/{transactionId}, or register a destination with POST /api/webhooks. Balances change only after settlement. Start with Issue tokens, Make a transfer, Operations and their lifecycle, and Idempotency and retries.

Try a request in the API Reference or Postman

Open the linked endpoint, choose its request method and supply the fields shown by the schema. For protected endpoints, supply a current bearer token. Set API-Version to 1.0.0; replace imported placeholders such as <string> before sending. Use the gateway and organisation assigned to your environment.

Begin with a read. A 401 means the request has not authenticated; resolve it before testing writes. If ReadMe returns a browser or CORS error, compare the same method, URL, headers and body in Postman or a backend client. Keep the API response separate from a browser/proxy failure. Errors and Authentication describe the API's responses.

Use contract-derived examples in your backend

Implement a backend client includes GET, POST, PUT, PATCH and DELETE calls, with authentication, decimal amounts, idempotency and asynchronous outcome handling. The coverage map connects every public OpenAPI operation to its guide, code recipe and API Reference. Recipes regenerate from the YAML; they retain the source request examples and documented response statuses.