Partner API

Frontier HSA Partner API is a read-only REST API for approved company integrations. It does not submit, approve, deny, or change claims.

Base URL and OpenAPI

https://api.frontierhsa.ca/v1

The machine-readable contract is available at openapi.json.

Authentication

Frontier issues each integration a company-bound, read-only API key. Send the key as a Bearer token:

curl https://api.frontierhsa.ca/v1/members \
  -H "Authorization: Bearer $FRONTIER_API_KEY"

Store the key in a secret manager. Do not put it in browser code, source control, URLs, or logs. Plan administrators create keys under Settings → Advanced → API & webhooks. The full key is shown only once.

Every administrator-created key includes these read scopes:

• members:read
• benefits:read
• invoices:read

Endpoints

List endpoints accept limit from 1 to 100 and an optional cursor. Pass the returned next_cursor unchanged to request the next page. Monetary values are integer Canadian cents.

Responses include X-Request-Id and are never cached. Errors use application/problem+json with a stable code.

Example requests and responses

GET /members

{
  "data": [
    {
      "id": "b2bc8633-4361-4d30-a1e2-029ec29ff56d",
      "first_name": "Alex",
      "last_name": "Chen",
      "email": "alex.chen@example.com",
      "role": "employee",
      "status": "active",
      "coverage_start_date": "2026-01-01",
      "termination_effective_date": null,
      "created_at": "2025-11-03T14:22:01.000Z"
    }
  ],
  "next_cursor": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

role is admin or employee. status is pending, active, or terminated.

GET /members/{memberId}

{
  "data": {
    "id": "b2bc8633-4361-4d30-a1e2-029ec29ff56d",
    "first_name": "Alex",
    "last_name": "Chen",
    "email": "alex.chen@example.com",
    "role": "employee",
    "status": "active",
    "coverage_start_date": "2026-01-01",
    "termination_effective_date": null,
    "created_at": "2025-11-03T14:22:01.000Z"
  }
}

GET /members/{memberId}/limits

{
  "data": {
    "member_id": "b2bc8633-4361-4d30-a1e2-029ec29ff56d",
    "benefit_class": {
      "id": "c1d2e3f4-5678-4abc-9def-0123456789ab",
      "name": "Standard"
    },
    "plan_year": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31",
      "next_start_date": "2027-01-01"
    },
    "annual_limit_cents": 150000
  }
}

benefit_class is null if the member has no assigned benefit class.

GET /members/{memberId}/balance

{
  "data": {
    "member_id": "b2bc8633-4361-4d30-a1e2-029ec29ff56d",
    "benefit_class": {
      "id": "c1d2e3f4-5678-4abc-9def-0123456789ab",
      "name": "Standard"
    },
    "plan_year": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31",
      "next_start_date": "2027-01-01"
    },
    "annual_limit_cents": 150000,
    "carryover_cents": 5000,
    "available_cents": 155000,
    "used_cents": 32000,
    "remaining_cents": 123000
  }
}

GET /claim-invoices

{
  "data": [
    {
      "id": "e5f6a7b8-9012-4cde-bfa1-23456789abcd",
      "claim_id": "c26-4x2p7",
      "member_id": "b2bc8633-4361-4d30-a1e2-029ec29ff56d",
      "claim_status": "paid",
      "payment_status": "completed",
      "claim_amount_cents": 12500,
      "fee_amount_cents": 500,
      "tax_amount_cents": 65,
      "total_amount_cents": 13065,
      "invoice_url": "https://invoices.frontierhsa.ca/inv_e5f6a7b8.pdf",
      "issued_at": "2026-02-01T10:00:00.000Z",
      "paid_at": "2026-02-04T09:12:00.000Z"
    }
  ],
  "next_cursor": null
}

claim_status is one of pending, approved, partial, denied, voided, paid. payment_status is pending, completed, or failed. claim_id matches c\d{2}-[23456789cfghjmpqrvwx]{5}.

GET /claim-invoices/{claimId}

{
  "data": {
    "id": "e5f6a7b8-9012-4cde-bfa1-23456789abcd",
    "claim_id": "c26-4x2p7",
    "member_id": "b2bc8633-4361-4d30-a1e2-029ec29ff56d",
    "claim_status": "paid",
    "payment_status": "completed",
    "claim_amount_cents": 12500,
    "fee_amount_cents": 500,
    "tax_amount_cents": 65,
    "total_amount_cents": 13065,
    "invoice_url": "https://invoices.frontierhsa.ca/inv_e5f6a7b8.pdf",
    "issued_at": "2026-02-01T10:00:00.000Z",
    "paid_at": "2026-02-04T09:12:00.000Z"
  }
}

Errors

All error responses use application/problem+json:

{
  "type": "https://api.frontierhsa.ca/problems/invalid_api_key",
  "title": "Authentication failed",
  "status": 401,
  "code": "INVALID_API_KEY",
  "detail": "The API key is invalid, expired, or revoked.",
  "request_id": "5e2f3a1c-...",
  "instance": "/v1/members"
}

Webhooks

Frontier can send these events to an approved public HTTPS endpoint:

• claim.approved
• invoice.issued

Example payload:

{
  "id": "evt_22dd5b358d365ff6213669f1732f8156",
  "type": "claim.approved",
  "created_at": "2026-09-16T15:04:05.000Z",
  "data": {
    "claim_id": "c26-2cfgh",
    "member_id": "b2bc8633-4361-4d30-a1e2-029ec29ff56d",
    "member_name": "Alex Chen",
    "status": "approved",
    "approved_amount_cents": 12500
  }
}

Every delivery includes:

• Webhook-Id: stable event ID for deduplication
• Webhook-Timestamp: Unix timestamp in seconds
• Webhook-Signature: one or more space-separated v1, base64 HMAC-SHA256 signatures

Verify the signature over the exact raw body using:

{Webhook-Timestamp}.{raw request body}

Need access?

Plan administrators can create keys and manage webhook endpoints under Settings → Advanced → API & webhooks. Contact support@frontierhsa.ca if you need help.