{"openapi":"3.1.0","info":{"title":"Frontier HSA Partner API","version":"1.0.0","description":"Read-only, company-scoped access to members, benefit limits, balances, and claim invoices.","contact":{"email":"support@frontierhsa.ca"}},"servers":[{"url":"https://api.frontierhsa.ca/v1"}],"paths":{"/members":{"get":{"operationId":"listMembers","summary":"List company members","security":[{"PartnerApiKey":[]}],"x-required-scope":"members:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A cursor-paginated member list","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Member"}},"next_cursor":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/members/{memberId}":{"get":{"operationId":"getMember","summary":"Get one company member","security":[{"PartnerApiKey":[]}],"x-required-scope":"members:read","parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The requested member","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Member"}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/members/{memberId}/limits":{"get":{"operationId":"getMemberLimits","summary":"Get a member's current benefit limit","security":[{"PartnerApiKey":[]}],"x-required-scope":"benefits:read","parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The current plan-year limit","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/BenefitLimit"}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/members/{memberId}/balance":{"get":{"operationId":"getMemberBalance","summary":"Get a member's current benefit balance","security":[{"PartnerApiKey":[]}],"x-required-scope":"benefits:read","parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The current plan-year balance","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/BenefitBalance"}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/claim-invoices":{"get":{"operationId":"listClaimInvoices","summary":"List claim invoices","security":[{"PartnerApiKey":[]}],"x-required-scope":"invoices:read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A cursor-paginated claim invoice list","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ClaimInvoice"}},"next_cursor":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}},"/claim-invoices/{claimId}":{"get":{"operationId":"getClaimInvoice","summary":"Get the invoice for a claim","security":[{"PartnerApiKey":[]}],"x-required-scope":"invoices:read","parameters":[{"name":"claimId","in":"path","required":true,"schema":{"type":"string","pattern":"^c[0-9]{2}-[23456789cfghjmpqrvwx]{5}$"}}],"responses":{"200":{"description":"The requested claim invoice","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ClaimInvoice"}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}}}}},"webhooks":{"claimApproved":{"post":{"summary":"A claim was approved or partially approved","parameters":[{"$ref":"#/components/parameters/WebhookId"},{"$ref":"#/components/parameters/WebhookTimestamp"},{"$ref":"#/components/parameters/WebhookSignature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimApprovedEvent"}}}},"responses":{"200":{"description":"Webhook accepted"}}}},"invoiceIssued":{"post":{"summary":"A claim invoice was issued","parameters":[{"$ref":"#/components/parameters/WebhookId"},{"$ref":"#/components/parameters/WebhookTimestamp"},{"$ref":"#/components/parameters/WebhookSignature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceIssuedEvent"}}}},"responses":{"200":{"description":"Webhook accepted"}}}}},"components":{"securitySchemes":{"PartnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"fhsa_...","description":"A company-bound API key with explicit read scopes. Send it only in the Authorization header."}},"parameters":{"WebhookId":{"name":"Webhook-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_(?:test_)?[0-9a-f]{32}$"}},"WebhookTimestamp":{"name":"Webhook-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"}},"WebhookSignature":{"name":"Webhook-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^v1,.+$"}}},"schemas":{"Problem":{"type":"object","required":["type","title","status","code","detail"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"instance":{"type":"string"}}},"Member":{"type":"object","required":["id","first_name","last_name","email","role","status","coverage_start_date","termination_effective_date","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","employee"]},"status":{"type":"string","enum":["pending","active","terminated"]},"coverage_start_date":{"type":"string","format":"date"},"termination_effective_date":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}}},"PlanYear":{"type":"object","required":["start_date","end_date","next_start_date"],"properties":{"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"next_start_date":{"type":"string","format":"date"}}},"BenefitClass":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"BenefitLimit":{"type":"object","required":["member_id","benefit_class","plan_year","annual_limit_cents"],"properties":{"member_id":{"type":"string","format":"uuid"},"benefit_class":{"oneOf":[{"$ref":"#/components/schemas/BenefitClass"},{"type":"null"}]},"plan_year":{"$ref":"#/components/schemas/PlanYear"},"annual_limit_cents":{"type":"integer","minimum":0}}},"BenefitBalance":{"allOf":[{"$ref":"#/components/schemas/BenefitLimit"},{"type":"object","required":["carryover_cents","available_cents","used_cents","remaining_cents"],"properties":{"carryover_cents":{"type":"integer","minimum":0},"available_cents":{"type":"integer","minimum":0},"used_cents":{"type":"integer","minimum":0},"remaining_cents":{"type":"integer","minimum":0}}}]},"ClaimInvoice":{"type":"object","required":["id","claim_id","member_id","claim_status","payment_status","claim_amount_cents","fee_amount_cents","tax_amount_cents","total_amount_cents","invoice_url","issued_at","paid_at"],"properties":{"id":{"type":"string","format":"uuid"},"claim_id":{"type":"string","pattern":"^c[0-9]{2}-[23456789cfghjmpqrvwx]{5}$"},"member_id":{"type":"string","format":"uuid"},"claim_status":{"type":"string","enum":["pending","approved","partial","denied","voided","paid"]},"payment_status":{"type":"string","enum":["pending","completed","failed"]},"claim_amount_cents":{"type":"integer","minimum":0},"fee_amount_cents":{"type":"integer","minimum":0},"tax_amount_cents":{"type":"integer","minimum":0},"total_amount_cents":{"type":"integer","minimum":0},"invoice_url":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"issued_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"paid_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"ClaimApprovedEvent":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string","pattern":"^evt_(?:test_)?[0-9a-f]{32}$"},"type":{"const":"claim.approved"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["claim_id","member_id","member_name","status","approved_amount_cents"],"properties":{"claim_id":{"type":"string","pattern":"^c[0-9]{2}-[23456789cfghjmpqrvwx]{5}$"},"member_id":{"type":"string","format":"uuid"},"member_name":{"type":"string"},"status":{"type":"string","enum":["approved","partial"]},"approved_amount_cents":{"type":"integer","minimum":0}}}}},"InvoiceIssuedEvent":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string","pattern":"^evt_(?:test_)?[0-9a-f]{32}$"},"type":{"const":"invoice.issued"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","required":["invoice_id","claim_id","member_id","member_name","claim_amount_cents","fee_amount_cents","tax_amount_cents","total_amount_cents","invoice_url"],"properties":{"invoice_id":{"type":"string","format":"uuid"},"claim_id":{"type":"string","pattern":"^c[0-9]{2}-[23456789cfghjmpqrvwx]{5}$"},"member_id":{"type":"string","format":"uuid"},"member_name":{"type":"string"},"claim_amount_cents":{"type":"integer","minimum":0},"fee_amount_cents":{"type":"integer","minimum":0},"tax_amount_cents":{"type":"integer","minimum":0},"total_amount_cents":{"type":"integer","minimum":0},"invoice_url":{"type":"string","format":"uri"}}}}}},"responses":{"Problem":{"description":"RFC 9457 Problem Details response","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}