{ "openapi": "3.0.1", "info": { "title": "Enterprise FE API", "description": "The Enterprise Front End API.", "version": "1.0" }, "servers": [ { "url": "https://dev.shc-integration.co.uk/fe", "description": "Public API" } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Health check.", "description": "Health check.", "operationId": "Health-Get", "parameters": [], "responses": { "200": { "description": "Payload of HealthReportResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthReportResponse" }, "example": { "status": "string", "entries": {} } } } }, "500": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/customers/{externalId}": { "patch": { "tags": [ "Customers" ], "summary": "Partially update customer details", "description": "Applies a partial update to the customer record identified by the supplied\nexternal identifier, using JSON Merge Patch semantics (RFC 7396).\n\nOnly the fields present in the request body are updated. Omitted fields are\nleft unchanged. Fields outside the documented allowlist are rejected with a\nvalidation error; attempts to modify system or unmanaged fields (for example,\n`externalId`, `email`, or state flags) are not permitted.\n\nFields fall into two tiers. **Immediately applicable** fields (`title`,\n`address`) are written straight away and the updated record is returned with\n`200`. **Verification-gated** fields (`firstName`, `middleName`, `lastName`,\n`dateOfBirth`) are not applied directly: submitting any of them creates a change request\nthat is verified by an external service — which may approve or reject it — and\nthe response is `202 Accepted` with the change request. Some verifications\nalso require supporting documents (for example a marriage certificate for a\nsurname change); the change request indicates whether evidence is required and\nwhich document types. Where a single request mixes both tiers, the immediately\napplicable fields are written and a change request is created for the rest.\n\nAuthorisation follows the same role-scoped model as the GET endpoint. A\nCustomer may update only their own record; broader roles may update records\nwithin their scope.\n\nAll successful updates are captured in the audit trail with\nbefore-and-after values. The API application log records only request\nmetadata — which fields were updated, when, and by whom — not the values\nthemselves, in line with UK GDPR data minimisation.\n\nInactive customer records cannot be updated; attempts return `410 Gone`.", "operationId": "Customer-Update-Patch", "parameters": [ { "name": "externalId", "in": "path", "description": "The external customer identifier (for example, `PER00000001`).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateFeCustomerRequest" }, "example": { "title": "string", "firstName": "string", "middleName": "string", "lastName": "string", "dateOfBirth": "string", "email": "string", "address": { "addressLine1": "string", "addressLine2": "string", "city": "string", "county": "string", "postcode": "string", "country": "string" } } } } }, "responses": { "200": { "description": "Customer details updated successfully. The full current record is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_updateFeCustomerResponse" }, "example": { "data": { "externalId": "string", "email": "string", "title": "string", "firstName": "string", "lastName": "string", "dateOfBirth": "string", "address": { "addressLine1": "string", "addressLine2": "string", "city": "string", "county": "string", "postcode": "string", "country": "string" } }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request could not be processed due to validation failures or malformed\ninput. Field-level details are provided in the `errors` array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No customer record exists for the supplied external identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } }, "get": { "tags": [ "Customers" ], "summary": "Retrieve customer details by external identifier", "description": "Returns a curated payload of personal details for the customer identified by\nthe supplied external identifier. The response is a shaped data transfer\nobject — internal system fields are not exposed.\n\nAuthorisation is role-scoped. A caller with the Customer role may retrieve\nonly their own record. Callers with broader roles (SchemeAdministrator,\nClaimsAssessor) may retrieve records within their scope. Requests outside\nthe caller's scope return `403 Forbidden`.\n\nInactive customer records return `410 Gone` with a body indicating the record\nexists but is no longer active.", "operationId": "Customer-GetByExternalId-Get", "parameters": [ { "name": "externalId", "in": "path", "description": "The external customer identifier (for example, `PER00000001`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_updateFeCustomerResponse" }, "example": { "data": { "externalId": "string", "email": "string", "title": "string", "firstName": "string", "lastName": "string", "dateOfBirth": "string", "address": { "addressLine1": "string", "addressLine2": "string", "city": "string", "county": "string", "postcode": "string", "country": "string" } }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No customer record exists for the supplied external identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/organisations": { "post": { "tags": [ "Organisations" ], "summary": "Create an organisation", "description": "Register a new organisation in the downstream Core system.", "operationId": "Organisation-Create-Post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createFeOrganisationRequest" }, "example": { "name": "string", "email": "string", "phone": "string", "address": { "addressLine1": "string", "addressLine2": "string", "city": "string", "county": "string", "postalCode": "string", "country": "string" }, "director": { "personExternalId": "string", "effectiveFrom": "string", "effectiveTo": "string", "notes": "string" } } } } }, "responses": { "201": { "description": "Organisation created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_createFeOrganisationResponse" }, "example": { "data": { "externalId": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/locations": { "post": { "tags": [ "Locations" ], "summary": "Create a location", "description": "Register a new location for an organisation in the downstream Core system.", "operationId": "Location-Create-Post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createFeLocationRequest" }, "example": { "name": "string", "organisationExternalId": "string", "addressLine1": "string", "addressLine2": "string", "addressLine3": "string", "city": "string", "county": "string", "postalCode": "string", "country": "string", "locationCategory": "string", "latitude": 0, "longitude": 0, "emailAddress": "string", "phoneNumber": "string", "notes": "string" } } } }, "responses": { "201": { "description": "Location created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_createFeLocationResponse" }, "example": { "data": { "externalId": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/reference-data/{listName}": { "get": { "tags": [ "ReferenceData" ], "summary": "Get the values of a named choice list", "description": "Returns the choices (code + label pairs) for the named choice list.\nInternal numeric identifiers and platform-specific field names are\nimplementation details and are intentionally omitted from the response.", "operationId": "ReferenceData-GetChoiceList-Get", "parameters": [ { "name": "listName", "in": "path", "description": "camelCase identifier of the choice list. Case-sensitive exact match\nagainst the catalogue.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The named choice list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_getChoiceListResponse" }, "example": { "data": { "name": "string", "scope": "string", "choices": [ { "code": "string", "label": "string" } ], "catalogueVersion": "string", "catalogueGeneratedAt": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed. For this API, typically caused by a `listName`\npath segment that does not match the required pattern.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "The requested choice list is not present in the catalogue. The response\nbody does not enumerate the available list names (no information leakage).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/reference-data": { "get": { "tags": [ "ReferenceData" ], "summary": "List available choice lists (manifest)", "description": "Returns a lightweight manifest of every choice list available in the\ncatalogue. Clients call `GET /v1/reference-data/{listName}` to retrieve\nthe choices themselves.", "operationId": "ReferenceData-ListChoiceLists-Get", "parameters": [], "responses": { "200": { "description": "Manifest of available choice lists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_listChoiceListsResponse" }, "example": { "data": { "items": [ { "name": "string", "scope": "string", "choiceCount": 0 } ], "catalogueVersion": "string", "catalogueGeneratedAt": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/products/{externalId}": { "get": { "tags": [ "Products" ], "summary": "Retrieve a product by its external product reference", "description": "Returns a fully expanded product payload — provider, provider settings,\nall versions, and for each version the benefits, benefit coverages,\nlevels, level benefits and level pricing.", "operationId": "Product-GetByExternalId-Get", "parameters": [ { "name": "externalId", "in": "path", "description": "External product reference, example - `PRD0000010006`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_getFeProductResponse" }, "example": { "data": { "reference": "string", "name": "string", "description": "string", "status": "string", "provider": { "name": "string", "description": "string", "settings": [ { "name": "string", "value": "string" } ] }, "versions": [ { "number": "string", "effectiveFrom": "string", "effectiveTo": "string", "name": "string", "status": "string", "pricingMethod": "string", "dependentHandling": "string", "maxDependentAge": 0, "additionalAdultHandling": "string", "maxAdditionalAdults": 0, "benefits": [ { "name": "string", "benefit": "string", "status": "string", "isCore": true, "coveredEntityType": "string", "coverage": [ { "name": "string", "coveredEntityType": "string", "coverageType": "string", "status": "string", "qualifyingPeriodMonths": 0, "benefitPeriodMonths": 0, "benefitPeriodBasis": "string", "excessType": "string", "excessValue": 0, "limitType": "string", "limitValue": 0, "maxReimbursementValue": 0, "maxPaybackType": "string", "maxPaybackValue": 0, "potAllocation": "string", "claimBasis": "string" } ] } ], "levels": [ { "level": 0, "name": "string", "description": "string", "status": "string", "pricing": [ { "name": "string", "memberType": "string", "amount": 0, "effectiveFrom": "string", "approvedOn": "string", "effectiveTo": "string", "status": "string", "rateType": "string", "paymentFrequency": "string", "formula": "string" } ], "benefits": [ { "name": "string", "benefit": "string", "status": "string", "qualifyingPeriod": "string", "minReimbursementValue": 0, "maxReimbursementValue": 0, "maxPaybackType": "string", "maxPaybackValue": 0, "dependentMinReimbursementValue": 0, "dependentMaxReimbursementValue": 0, "additionalAdultMinReimbursementValue": 0, "additionalAdultMaxReimbursementValue": 0, "familySharedPoolValue": 0, "dependentSharedPoolValue": 0 } ] } ] } ] }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed (e.g. invalid product reference format).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No product was found for the supplied reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/policies/{policyReference}": { "get": { "tags": [ "Policies" ], "summary": "Retrieve a policy by its public reference", "description": "Returns a fully expanded policy payload - policy details, the resolved\nproduct / version / cover level references, pricing, policy holder\n(person, contact, consents), payer and Direct Debit details,\nadditional adults, dependants, referral data, and recorded audit\nevents.\n\nThe response mirrors the structure of the create-policy request body\nand adds system-generated identifiers (`policyId`, `policyReference`,\n`contactId`, `contactExternalId`), the policy `status`, and audit\nmetadata.\n\nThe response also carries the `provider` that underwrites the policy\n(identifier, reference and name), and a `coveredEntityReference`\n(`CVE...`) on the policy holder, on each additional adult and on each\ndependant. Use a `coveredEntityReference` with\n`GET /v1/policies/{policyReference}/covered-entities/{coveredEntityReference}`\nto read the details of that covered entity.\n\nAccess is subject to object-level authorization (see\n**Authentication and authorization** in the API description): the\ncaller must hold an active role on the requested policy. A caller\nwith no active role receives `404`, indistinguishable from an unknown\nreference.", "operationId": "Policy-GetByReference-Get", "parameters": [ { "name": "policyReference", "in": "path", "description": "External policy reference, example - `POL-0000010014`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Policy successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_getFePolicyResponse" }, "example": { "data": { "policyId": "string", "policyReference": "string", "contactId": "string", "contactExternalId": "string", "name": "string", "status": "string", "channel": "string", "quoteReference": "string", "liveDate": "string", "fundingType": "string", "provider": { "providerId": "string", "providerReference": "string", "name": "string" }, "product": { "productReference": "string", "brandReference": "string", "coverLevel": "string", "productVersion": "string" }, "pricing": { "source": "string", "grossPremium": "string", "grossPremiumFormatted": "string", "currency": "string", "paymentFrequency": "string" }, "policyHolder": { "coveredEntityReference": "string", "contactId": "string", "contactExternalId": "string", "person": { "firstName": "string", "lastName": "string", "dateOfBirth": "string" }, "contact": { "emailAddress": "string", "phoneMobile": "string", "phoneLandline": "string", "address": { "line1": "string", "line2": "string", "line3": "string", "city": "string", "postalCode": "string", "countryCode": "string", "verified": true, "verificationId": "string" } }, "consents": { "termsAcceptedOn": "string", "ipidAcknowledgedOn": "string", "marketingOptIn": true } }, "payer": { "person": { "firstName": "string", "lastName": "string", "dateOfBirth": "string" }, "contact": { "emailAddress": "string", "phoneMobile": "string", "phoneLandline": "string", "address": { "line1": "string", "line2": "string", "line3": "string", "city": "string", "postalCode": "string", "countryCode": "string", "verified": true, "verificationId": "string" } }, "directDebit": { "bankName": "string", "accountHolderName": "string", "sortCode": "string", "accountNumber": "string", "collectionDay": 0, "verified": true, "mandateAcceptedAt": "string" } }, "additionalAdults": [ { "coveredEntityReference": "string", "contactId": "string", "contactExternalId": "string", "person": { "firstName": "string", "lastName": "string", "dateOfBirth": "string" } } ], "dependants": [ { "coveredEntityReference": "string", "contactId": "string", "contactExternalId": "string", "person": { "firstName": "string", "lastName": "string", "dateOfBirth": "string" } } ], "events": [ { "eventType": "string", "name": "string", "description": "string", "eventDate": "string", "effectiveDate": "string" } ], "referralCode": "string", "referringPolicyReference": "string", "createdOn": "string", "modifiedOn": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation (e.g. missing required\nfields, invalid formats, unresolvable product/version/cover-level\nreference). Business-rule rejections (for example the matched customer\nbeing flagged as banned) are also returned here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "The request did not present a valid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No policy was found for the supplied reference, or the caller does not\nhold an active role on it. The two cases are deliberately\nindistinguishable (see *Authentication and authorization* in the API\ndescription) so the existence of other customers' policies is not\ndisclosed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/policies": { "post": { "tags": [ "Policies" ], "summary": "Create a new policy from a direct application (no previous quote)", "description": "Creates a new policy at **Draft** status and the supporting customer,\npolicy holder role, covered entity, and audit event records in a\nsingle atomic transaction.\n\nBusiness rules executed during the call:\n\n - **Existing customer match** - the platform searches for an\n existing customer using surname + date of birth + email address.\n A match reuses the existing record; no match creates a new one.\n - **Banned customer rejection** - if the matched customer's\n `bannedCustomer` flag is true, the application is rejected with\n HTTP 400 / `CUSTOMER_BANNED`.\n - **Similar policy detection** - if the matched customer already\n holds a policy on the same product and product version, the\n create proceeds and a non-blocking `SIMILAR_POLICY_EXISTS`\n warning is returned in `meta.warnings`.\n\nAtomicity guarantee: if any inner write fails, all writes for the\napplication are rolled back so the caller can cleanly retry.", "operationId": "Policy-Create-Post", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createFePolicyRequest" }, "example": { "startDate": "string", "fundingType": "string", "product": { "productReference": "string", "brandReference": "string", "coverLevel": "string", "productVersion": "string" }, "pricing": { "grossPremium": 0, "currency": "string", "paymentFrequency": "string" }, "policyHolder": { "person": { "firstName": "string", "lastName": "string", "dateOfBirth": "string" }, "contact": { "emailAddress": "string", "phoneMobile": "string", "phoneLandline": "string", "address": { "line1": "string", "line2": "string", "line3": "string", "city": "string", "postalCode": "string", "countryCode": "string" } }, "directDebit": { "collectionDay": 0 } } } } } }, "responses": { "201": { "description": "Policy successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_createFePolicyResponse" }, "example": { "data": { "policyReference": "string", "contactExternalId": "string", "status": "string", "liveDate": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation (e.g. missing required\nfields, invalid formats, unresolvable product/version/cover-level\nreference). Business-rule rejections (for example the matched customer\nbeing flagged as banned) are also returned here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/policies/{policyReference}/events": { "post": { "tags": [ "Policies" ], "summary": "Record a new audit event against a policy", "description": "Appends a new audit / lifecycle event to an existing policy,\nidentified by its public reference. Events provide an immutable,\nappend-only history of what happened to a policy and when - policy\ncreation, cover-level changes, premium changes, cancellations,\nrenewals, and so on - supporting servicing visibility, audit, and FCA\nrecord-keeping.\n\nThe event is written as a single record linked to the parent policy.\nOptional **before / after** detail (status, funding type, member type,\ncover level, premium) may be supplied through the `change` object for\ntransition-type events (for example `COVER_LEVEL_CHANGE` or\n`PREMIUM_CHANGE`).\n\nThis operation is append-only: it creates a new event and never\nmutates the policy header or any existing event. The authenticated\nprincipal is recorded against the event as the performer.\n\nResponses follow the Sovereign Health Care API Design Standards: a\nsuccessful create returns the created event inside a `data` + `meta`\nenvelope; errors use RFC 9457 `application/problem+json`.", "operationId": "Policy-CreateEvent-Post", "parameters": [ { "name": "policyReference", "in": "path", "description": "External policy reference, example - `POL-0000010014`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createFePolicyEventRequest" }, "example": { "eventType": "string", "eventDate": "string", "effectiveDate": "string", "name": "string", "description": "string", "status": "string", "externalId": "string", "change": { "previousStatus": "string", "newStatus": "string", "previousFundingType": "string", "newFundingType": "string", "previousMemberType": "string", "newMemberType": "string", "previousProductVersionLevelId": "string", "newProductVersionLevelId": "string", "previousPremium": "string", "newPremium": "string", "currency": "string" } } } } }, "responses": { "201": { "description": "Policy event successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_createFePolicyEventResponse" }, "example": { "data": { "eventId": "string", "policyReference": "string", "policyId": "string", "eventType": "string", "name": "string", "description": "string", "eventDate": "string", "effectiveDate": "string", "status": "string", "initiatedBy": "string", "performedBy": "string", "change": { "previousStatus": "string", "newStatus": "string", "previousFundingType": "string", "newFundingType": "string", "previousMemberType": "string", "newMemberType": "string", "previousProductVersionLevelId": "string", "newProductVersionLevelId": "string", "previousPremium": "string", "newPremium": "string", "currency": "string" }, "createdOn": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation (e.g. missing required\nfields, invalid formats, unresolvable product/version/cover-level\nreference). Business-rule rejections (for example the matched customer\nbeing flagged as banned) are also returned here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No policy was found for the supplied reference, or the caller does not\nhold an active role on it. The two cases are deliberately\nindistinguishable (see *Authentication and authorization* in the API\ndescription) so the existence of other customers' policies is not\ndisclosed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "409": { "description": "A policy event with the supplied externalId already exists. The event\nis not created again and the existing event is unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "422": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/customers/{externalId}/policies": { "get": { "tags": [ "Customers" ], "summary": "List the policies a customer holds", "description": "Returns a list of policies for a given customer identified by their reference.\nThe customer is the **policy holder**.\n\nThe response is a paged collection per the Sovereign Health Care API Design\nStandards: the `data` array carries the policy summaries, the `pagination`\nblock carries navigation state, and `meta` carries correlation metadata. A\ncustomer with no qualifying policies receives `200 OK` with `data: []` —\nan empty collection is not an error.", "operationId": "Customer-GetPolicies-Get", "parameters": [ { "name": "externalId", "in": "path", "description": "The external customer identifier (for example, `PER00000001`).", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of policies to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request - the page size cannot change part-way through a paging sequence.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Policies retrieved successfully. May be an empty collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_getFeCustomerPolicyResponse" }, "example": { "data": [ { "policyId": "string", "policyReference": "string", "name": "string", "status": "string", "customerRole": "string", "liveDate": "string", "product": { "productReference": "string", "productName": "string", "productVersion": "string", "productVersionReference": "string", "coverLevel": "string", "coverLevelName": "string" }, "pricing": { "grossPremium": "string", "currency": "string", "paymentFrequency": "string" }, "policyHolder": { "contactExternalId": "string", "firstName": "string", "lastName": "string", "fullName": "string" }, "createdOn": "string", "modifiedOn": "string" } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but not permitted to access or modify this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No customer record exists for the supplied external identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "The customer record exists but has been deactivated. No data is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/me/portal-roles": { "get": { "tags": [ "PortalRoles" ], "summary": "List portal role assignments for the customer", "description": "Returns the list of active portal role assignments held by the customer. The API derives the Entra object identifier (`oid`) from the bearer\ntoken and resolves the matching PortalUser records, filtering\nto those marked active.\n\nA single Entra identity may hold multiple portal role assignments (for\nexample, a Customer who is also a SchemeAdministrator on a corporate scheme).\nEach assignment is returned as a discrete `PortalRole` entry.\n\nAn authenticated caller with no active portal role assignments receives a\n`200 OK` response with `data: []`. This is not an error condition — it\nindicates a recognised identity that has not yet been onboarded to any\nportal role.\n\nThis endpoint is the canonical mechanism for portals and broker integrations\nto discover the caller's available contexts after sign-in. It does not\nrequire a path parameter; identity is taken from the bearer token alone.", "operationId": "PortalRoles-ListMyPortalRoles-Get", "parameters": [ { "name": "pageSize", "in": "query", "description": "Number of portal role assignments to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request - the page size cannot change part-way through a paging sequence.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Portal role assignments retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_portalRoleResponse" }, "example": { "data": [ { "portalUserId": "string", "externalId": "string", "name": "string", "email": "string", "entraObjectId": "string", "role": "string", "tenantType": "string", "isActive": true, "lastLogin": "string", "person": { "contactId": "string", "externalId": "string", "firstName": "string", "lastName": "string", "fullName": "string", "email": "string" }, "organisation": { "organisationId": "string", "externalId": "string", "name": "string" } } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/me/policies": { "get": { "tags": [ "Policies" ], "summary": "List the policies the authenticated caller holds a role on", "description": "Returns the policies on which the authenticated caller currently\nholds an **active** policy role.\n\nThe caller is resolved from the bearer token's identity to the linked\nperson, and the response lists the policies on which that person holds\nan active role - a current, active role whose effective period includes\ntoday's date.\n\nEach policy appears once; where the caller holds more than one role\non the same policy (for example both **Policy Holder** and\n**Payer**), all such roles are listed in `policyRoleTypes`. The\npolicies are returned in the standard collection envelope `data`\narray; callers with no active policy roles receive an empty `data`\narray.", "operationId": "Policies-ListMyPolicies-Get", "parameters": [ { "name": "pageSize", "in": "query", "description": "Number of policies to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request - the page size cannot change part-way through a paging sequence.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The caller's accessible policies were successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_myPolicyResponse" }, "example": { "data": [ { "policyReference": "string", "name": "string", "status": "string", "policyRoleTypes": [ "string" ] } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation (e.g. missing required\nfields, invalid formats, unresolvable product/version/cover-level\nreference). Business-rule rejections (for example the matched customer\nbeing flagged as banned) are also returned here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The authenticated principal is not permitted to perform the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/me/schemes": { "get": { "tags": [ "Schemes" ], "summary": "List schemes the caller has access to", "description": "Returns the schemes the authenticated caller has access to. Access is granted\nvia the caller's portal-role scheme assignments. The caller's Entra object\nidentifier (oid) is resolved from the bearer token; no path parameter is\nrequired. An authenticated caller with no scheme grants receives `200` with an\nempty list.", "operationId": "Schemes-ListMySchemes-Get", "parameters": [ { "name": "pageSize", "in": "query", "description": "Number of schemes to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request - the page size cannot change part-way through a paging sequence.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The schemes the caller can access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_mySchemeResponse" }, "example": { "data": [ { "schemeReference": "string", "name": "string", "organisation": { "reference": "string", "name": "string" }, "effectiveFrom": "string", "effectiveTo": "string" } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{externalId}/members": { "post": { "tags": [ "SchemeMembers" ], "summary": "Add a scheme member", "description": "Adds a member to the scheme. firstName, lastName, employeeNumber and email are all required so the member can be matched against existing Person records (a Person is created if none matches). enrolmentDate is set from effectiveDate; the member starts pending.", "operationId": "SchemeMember-Add-Post", "parameters": [ { "name": "externalId", "in": "path", "description": "Scheme reference (^SCH\\d{9}$, e.g. SCH000000000).", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addSchemeMemberRequest" }, "example": { "firstName": "string", "lastName": "string", "employeeNumber": "string", "email": "string", "effectiveDate": "string", "memberType": "string" } } } }, "responses": { "201": { "description": "Member added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_schemeMemberResponse" }, "example": { "data": { "schemeMemberReference": "string", "employeeNumber": "string", "personExternalId": "string", "firstName": "string", "lastName": "string", "email": "string", "memberType": "string", "memberStatus": "string", "isActive": true, "enrolmentDate": "string", "terminationDate": "string", "level": { "reference": "string", "name": "string" }, "policyReference": "string", "createdAt": "string", "modifiedAt": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "409": { "description": "The request conflicts with the current state of the resource (for example,\nan optimistic concurrency violation or a duplicate member).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } }, "get": { "tags": [ "SchemeMembers" ], "summary": "List scheme members", "description": "Retrieve a page of the members of a scheme the caller administers. Members of every status are returned, including terminated and opted-out. Ordered by employee number. Authorisation: 403 when the caller holds no grant on the scheme - or the scheme is unknown - which are indistinguishable so scheme references cannot be enumerated; 404 when the caller does not resolve to a portal identity; 410 when that identity is inactive.", "operationId": "Scheme-ListMembers-Get", "parameters": [ { "name": "externalId", "in": "path", "description": "Scheme reference (^SCH\\d{9}$, e.g. SCH000000000).", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of members to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request - the page size cannot change part-way through a paging sequence.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of scheme members.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_schemeMemberResponse" }, "example": { "data": [ { "schemeMemberReference": "string", "employeeNumber": "string", "personExternalId": "string", "firstName": "string", "lastName": "string", "email": "string", "memberType": "string", "memberStatus": "string", "isActive": true, "enrolmentDate": "string", "terminationDate": "string", "level": { "reference": "string", "name": "string" }, "policyReference": "string", "createdAt": "string", "modifiedAt": "string" } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{externalId}/members/{schemeMemberReference}": { "delete": { "tags": [ "SchemeMembers" ], "summary": "Remove a scheme member", "description": "Removes (terminates) a member from the scheme, identified by the unique scheme member reference, with the given effective date. Soft termination: sets terminationDate and status=terminated, preserving the record for audit. The reference resolves to exactly one member within the scheme, so removal is unambiguous even when employee numbers are duplicated.", "operationId": "SchemeMember-Remove-Delete", "parameters": [ { "name": "externalId", "in": "path", "description": "Scheme reference (^SCH\\d{9}$).", "required": true, "schema": { "type": "string" } }, { "name": "schemeMemberReference", "in": "path", "description": "Unique external-facing identifier of the scheme member to remove. Obtain it from the list-members or add-member response.", "required": true, "schema": { "type": "string" } }, { "name": "effectiveDate", "in": "query", "description": "Effective (termination) date for removing the member.", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "Optimistic concurrency control. Use '*' to require the resource to exist, or provide an ETag from a previous GET.", "schema": { "type": "string" } } ], "responses": { "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "409": { "description": "The request conflicts with the current state of the resource (for example,\nan optimistic concurrency violation or a duplicate member).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "The resource exists but has been soft-deleted. No data is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "204": { "description": "No description" } } } }, "/v1/policies/{policyReference}/claims/quick": { "post": { "tags": [ "Claims" ], "summary": "Quick-create a draft claim", "description": "Starts a claim against the policy by returning a draft to work in. Drafts\nare persistent: if the caller already has an open draft claim for this\npolicy, that existing draft is returned (`200`); otherwise a new empty\ndraft is created (`201`). The policy is taken from the path, so no request\nbody is required. Returns only the claim reference.", "operationId": "quickCreateClaim", "parameters": [ { "name": "policyReference", "in": "path", "description": "Policy Reference Number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "An open draft already existed for this policy; the existing draft is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_quickCreateClaimResponse" }, "example": { "data": { "claimReference": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "201": { "description": "New draft claim created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_quickCreateClaimResponse" }, "example": { "data": { "claimReference": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "The resource does not exist, or the caller is not permitted to see it\n(returned in place of 403 for non-disclosure).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is unavailable or timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/product-versions/{productVersionReference}/benefits": { "get": { "tags": [ "Products" ], "summary": "List the benefits defined on a product version", "description": "Returns the benefits configured on a product version - the selectable\nbenefits for a claim line item. Used to populate the benefit picker when\nadding a claim line item: the caller selects a benefit and its\n`reference` is sent as the line item's `benefitReference`.\n\n`productVersionReference` is the product version's external reference,\nobtained from the policy's product version.", "operationId": "ProductVersion-ListBenefits-Get", "parameters": [ { "name": "productVersionReference", "in": "path", "description": "External reference of the product version, used as an alternate key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product version benefits successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_listProductVersionBenefitsResponse" }, "example": { "data": { "items": [ { "reference": "string", "name": "string", "benefit": "string", "isCore": true, "status": "string", "coveredEntityType": "string" } ] }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed (e.g. invalid product reference format).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "The request did not present a valid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No product was found for the supplied reference.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/policies/{policyReference}/covered-entities": { "get": { "tags": [ "Policies" ], "summary": "List the covered entities (people/animals) on a policy", "description": "Returns the entities covered by the policy - the people (and, for some\nproducts, animals) that claims can be made for. Used to populate the\nclaimant picker when adding a claim line item: the caller selects a\ncovered entity and its `coveredEntityReference` (`CVE...`) is sent as\nthe line item's `claimantReference`.\n\nOnly active covered entities are returned.\n\nAccess is subject to object-level authorization: the caller must hold an\nactive role on the policy. A caller with no active role receives `404`,\nindistinguishable from an unknown reference.", "operationId": "Policy-ListCoveredEntities-Get", "parameters": [ { "name": "policyReference", "in": "path", "description": "External policy reference, example - `POL-0000010014`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Covered entities successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_listCoveredEntitiesResponse" }, "example": { "data": { "items": [ { "coveredEntityReference": "string", "name": "string", "entityType": "string", "memberType": "string", "status": "string", "effectiveFrom": "string", "effectiveTo": "string", "person": { "firstName": "string", "lastName": "string", "fullName": "string", "email": "string", "dateOfBirth": "string" } } ] }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation (e.g. missing required\nfields, invalid formats, unresolvable product/version/cover-level\nreference). Business-rule rejections (for example the matched customer\nbeing flagged as banned) are also returned here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "The request did not present a valid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No policy was found for the supplied reference, or the caller does not\nhold an active role on it. The two cases are deliberately\nindistinguishable (see *Authentication and authorization* in the API\ndescription) so the existence of other customers' policies is not\ndisclosed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/claims/{claimReference}/line-items": { "post": { "tags": [ "Claims" ], "summary": "Create a claim line item", "description": "Resolve the caller at the edge, then add a line item to a draft claim the caller may see.", "operationId": "createClaimLineItem", "parameters": [ { "name": "claimReference", "in": "path", "description": "Claim Reference Number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createClaimLineItemRequest" }, "example": { "benefitReference": "string", "claimantReference": "string", "claimDate": "string", "benefitDate": "string", "totalCost": 0, "invoiceReference": "string" } } } }, "responses": { "201": { "description": "Created claim line item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_claimLineItem" }, "example": { "data": { "claimLineItemReference": "string", "name": "string", "lineStatus": "string", "claimDate": "string", "benefitDate": "string", "totalCost": 0, "totalAmountCovered": 0, "excessApplied": 0, "copayApplied": 0, "invoiceReference": "string", "externalId": "string", "benefit": { "benefitReference": "string", "name": "string" }, "claimant": { "coveredEntityReference": "string", "name": "string" } }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "The resource does not exist, or the caller is not permitted to see it\n(returned in place of 403 for non-disclosure).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "409": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is unavailable or timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/policies/{policyReference}/claims": { "get": { "tags": [ "Claims" ], "summary": "List claims for a policy", "description": "Retrieve the claims raised against a policy the caller may see, as normalised summaries. Optionally narrowed by claim status and by creation-date range.", "operationId": "getPolicyClaims", "parameters": [ { "name": "policyReference", "in": "path", "description": "Policy Reference Number", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Return only claims in this status. One of: DRAFT, CANCELLED, ABANDONED, SUBMITTED, IN_PROGRESS, FLAGGED_FOR_REVIEW, IN_REVIEW, ON_HOLD, REJECTED, ACCEPTED. Matched case-insensitively.", "schema": { "type": "string" } }, { "name": "createdFrom", "in": "query", "description": "Return only claims created at or after this ISO-8601 date-time, e.g. 2026-01-01T00:00:00Z.", "schema": { "type": "string" } }, { "name": "createdTo", "in": "query", "description": "Return only claims created at or before this ISO-8601 date-time, e.g. 2026-01-31T23:59:59Z. Must not be earlier than 'createdFrom'.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of claims to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request - the page size cannot change part-way through a paging sequence.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of claims", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_getPolicyClaimResponse" }, "example": { "data": [ { "claimReference": "string", "name": "string", "status": "string", "subStatus": "string", "totalAmountClaimed": 0, "totalAmountCovered": 0, "lineItemCount": 0, "createdAt": "string", "updatedAt": "string" } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but not permitted to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "The resource does not exist, or the caller is not permitted to see it\n(returned in place of 403 for non-disclosure).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } }, "post": { "tags": [ "Claims" ], "summary": "Create a claim against a policy", "description": "Resolve the caller at the edge, then create and submit a complete claim (header + line items) against a policy the caller may see in a single request.", "operationId": "createClaim", "parameters": [ { "name": "policyReference", "in": "path", "description": "Policy Reference Number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createClaimRequest" }, "example": { "name": "string", "totalAmountClaimed": 0, "payoutBasis": "string", "externalId": "string", "lineItems": [ { "benefitReference": "string", "claimantReference": "string", "claimDate": "string", "benefitDate": "string", "totalCost": 0, "invoiceReference": "string" } ] } } } }, "responses": { "201": { "description": "Created claim", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_claim" }, "example": { "data": { "claimReference": "string", "name": "string", "status": "string", "rejectionReason": "string", "payoutBasis": "string", "totalAmountClaimed": 0, "policyReference": "string", "lineItems": [ { "claimLineItemReference": "string", "name": "string", "lineStatus": "string", "claimDate": "string", "benefitDate": "string", "totalCost": 0, "totalAmountCovered": 0, "excessApplied": 0, "copayApplied": 0, "invoiceReference": "string", "externalId": "string", "benefit": { "benefitReference": "string", "name": "string" }, "claimant": { "coveredEntityReference": "string", "name": "string" } } ] }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/claims/{claimReference}/line-items/{claimLineItemReference}": { "patch": { "tags": [ "Claims" ], "summary": "Update a claim line item", "description": "Resolve the caller at the edge, then apply a partial update to a line item on a claim the caller may see. Only the supplied properties change; a property sent as null is cleared.", "operationId": "updateClaimLineItem", "parameters": [ { "name": "claimReference", "in": "path", "description": "Claim Reference Number", "required": true, "schema": { "type": "string" } }, { "name": "claimLineItemReference", "in": "path", "description": "Claim Line Item Reference Number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateClaimLineItemRequest" }, "example": { "name": "string", "claimDate": "string", "benefitDate": "string", "totalCost": 0, "totalAmountCovered": 0, "excessApplied": 0, "copayApplied": 0, "invoiceReference": "string", "benefitReference": "string", "claimantReference": "string" } } } }, "responses": { "200": { "description": "Updated claim line item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_updateClaimLineItemResponse" }, "example": { "data": { "claimLineItemReference": "string", "name": "string", "lineStatus": "string", "claimDate": "string", "benefitDate": "string", "totalCost": 0, "totalAmountCovered": 0, "excessApplied": 0, "copayApplied": 0, "invoiceReference": "string", "externalId": "string", "benefit": { "benefitReference": "string", "name": "string" }, "claimant": { "coveredEntityReference": "string", "name": "string" } }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "The resource does not exist, or the caller is not permitted to see it\n(returned in place of 403 for non-disclosure).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is unavailable or timed out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{schemeReference}/collections/{schemeCollectionReference}": { "get": { "tags": [ "Schemes" ], "summary": "Get a scheme collection", "description": "Returns a single collection belonging to the scheme, addressed by its\ncollection reference. Provides the header detail (due date, status, member\ncount and totals) for the collection drill-down.", "operationId": "Scheme-GetCollection-Get", "parameters": [ { "name": "schemeReference", "in": "path", "description": "Scheme reference (e.g. SCH000000000).", "required": true, "schema": { "type": "string" } }, { "name": "schemeCollectionReference", "in": "path", "description": "External identifier of the scheme collection. Obtain it from\n`schemeCollectionReference` in the list-collections response. Treat as an\nopaque string; the reference format is not yet finalised.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_schemeCollectionResponse" }, "example": { "data": { "schemeCollectionReference": "string", "name": "string", "dueDate": "string", "collectedDate": "string", "collectionStatus": "string", "memberCount": 0, "totalAmount": { "amount": 0, "currencyCode": "string" }, "collectedAmount": { "amount": 0, "currencyCode": "string" }, "isActive": true }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "The resource exists but has been soft-deleted. No data is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{schemeReference}/collections/{schemeCollectionReference}/scheme-policies": { "get": { "tags": [ "Schemes" ], "summary": "List the scheme policies making up a collection", "description": "Returns the per-policy breakdown of a single scheme collection: the policies\nthe collection is (or will be) applied to, and the amount attributed to each.\nThe collection must belong to the scheme in the path; otherwise `404` is\nreturned so a caller cannot read another scheme's breakdown.", "operationId": "Scheme-ListCollectionPolicies-Get", "parameters": [ { "name": "schemeReference", "in": "path", "description": "Scheme reference (e.g. SCH000000000).", "required": true, "schema": { "type": "string" } }, { "name": "schemeCollectionReference", "in": "path", "description": "External identifier of the scheme collection. Obtain it from\n`schemeCollectionReference` in the list-collections response. Treat as an\nopaque string; the reference format is not yet finalised.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of breakdown lines to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of scheme policies making up the collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_schemeCollectionPolicyResponse" }, "example": { "data": [ { "name": "string", "policyReference": "string", "amount": { "amount": 0, "currencyCode": "string" }, "grossAmount": { "amount": 0, "currencyCode": "string" }, "taxAmount": { "amount": 0, "currencyCode": "string" }, "isActive": true } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{schemeReference}/collection-schedules": { "get": { "tags": [ "Schemes" ], "summary": "List scheme collection schedules", "description": "Retrieve a page of the collection schedules of a scheme the caller administers - the plan behind the scheme premium collection. Ordered by start date, most recent first. Authorisation: 403 when the caller holds no grant on the scheme - or the scheme is unknown or soft-deleted, which are indistinguishable so scheme references cannot be enumerated; 404 when the caller does not resolve to a portal identity; 410 when that identity is inactive.", "operationId": "Scheme-ListCollectionSchedules-Get", "parameters": [ { "name": "schemeReference", "in": "path", "description": "Scheme reference (e.g. SCH000000000).", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of schedules to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of collection schedules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_schemeCollectionScheduleResponse" }, "example": { "data": [ { "schemeCollectionScheduleReference": "string", "name": "string", "startDate": "string", "endDate": "string", "collectionDay": 0, "paymentFrequency": "string", "paymentMethod": { "reference": "string", "name": "string" }, "isActive": true } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{schemeReference}/collections": { "get": { "tags": [ "Schemes" ], "summary": "List scheme collections", "description": "Returns the collection history for the scheme, most recent due date first.\nBoth past and forthcoming collections are included; a forthcoming collection\nhas no `collectedDate`. Optionally narrowed by due-date range and status.", "operationId": "Scheme-ListCollections-Get", "parameters": [ { "name": "schemeReference", "in": "path", "description": "Scheme reference (e.g. SCH000000000).", "required": true, "schema": { "type": "string" } }, { "name": "dueDateFrom", "in": "query", "description": "Include only collections whose `dueDate` falls on or after this date (inclusive).", "schema": { "type": "string" } }, { "name": "dueDateTo", "in": "query", "description": "Include only collections whose `dueDate` falls on or before this date (inclusive).", "schema": { "type": "string" } }, { "name": "collectionStatus", "in": "query", "description": "Include only collections with this status.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of collections to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it. The filters must be repeated unchanged alongside it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of collections.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_schemeCollectionResponse" }, "example": { "data": [ { "schemeCollectionReference": "string", "name": "string", "dueDate": "string", "collectedDate": "string", "collectionStatus": "string", "memberCount": 0, "totalAmount": { "amount": 0, "currencyCode": "string" }, "collectedAmount": { "amount": 0, "currencyCode": "string" }, "isActive": true } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{schemeReference}/invoices/{invoiceReference}": { "get": { "tags": [ "Schemes" ], "summary": "Get a scheme invoice", "description": "Returns a single invoice raised against the scheme, addressed by its invoice\nreference. Provides the header detail (invoice number, dates, status and\namounts) for the invoice drill-down.", "operationId": "Scheme-GetInvoice-Get", "parameters": [ { "name": "schemeReference", "in": "path", "description": "Scheme reference (e.g. SCH000000000).", "required": true, "schema": { "type": "string" } }, { "name": "invoiceReference", "in": "path", "description": "External identifier of the invoice. Obtain it from `invoiceReference` in the\nlist-invoices response. Treat as an opaque string; the reference format is\nnot yet finalised. This is not the same as `invoiceNumber`, which is the\nfinance-facing number shown to the administrator.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_schemeInvoiceResponse" }, "example": { "data": { "invoiceReference": "string", "invoiceNumber": "string", "invoiceDate": "string", "dueDate": "string", "paidDate": "string", "invoiceStatus": "string", "grossAmount": { "amount": 0, "currencyCode": "string" }, "netAmount": { "amount": 0, "currencyCode": "string" }, "taxAmount": { "amount": 0, "currencyCode": "string" }, "paidAmount": { "amount": 0, "currencyCode": "string" } }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "The resource exists but has been soft-deleted. No data is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{schemeReference}/invoices/{invoiceReference}/scheme-policies": { "get": { "tags": [ "Schemes" ], "summary": "List the scheme policies making up an invoice", "description": "Returns the per-policy breakdown of a single invoice: the policies the\ninvoice covers, and the amount attributed to each. The breakdown is resolved\nthrough the collection the invoice was raised for. The invoice must belong to\nthe scheme in the path; otherwise `404` is returned. An invoice that is not\nlinked to a collection returns an empty list.", "operationId": "Scheme-ListInvoicePolicies-Get", "parameters": [ { "name": "schemeReference", "in": "path", "description": "Scheme reference (e.g. SCH000000000).", "required": true, "schema": { "type": "string" } }, { "name": "invoiceReference", "in": "path", "description": "External identifier of the invoice. Obtain it from `invoiceReference` in the\nlist-invoices response. Treat as an opaque string; the reference format is\nnot yet finalised. This is not the same as `invoiceNumber`, which is the\nfinance-facing number shown to the administrator.", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of breakdown lines to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of scheme policies making up the invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_schemeCollectionPolicyResponse" }, "example": { "data": [ { "name": "string", "policyReference": "string", "amount": { "amount": 0, "currencyCode": "string" }, "grossAmount": { "amount": 0, "currencyCode": "string" }, "taxAmount": { "amount": 0, "currencyCode": "string" }, "isActive": true } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/schemes/{schemeReference}/invoices": { "get": { "tags": [ "Schemes" ], "summary": "List scheme invoices", "description": "Returns the invoices raised against the scheme, most recent invoice date\nfirst. Optionally narrowed by invoice-date range and status.", "operationId": "Scheme-ListInvoices-Get", "parameters": [ { "name": "schemeReference", "in": "path", "description": "Scheme reference (e.g. SCH000000000).", "required": true, "schema": { "type": "string" } }, { "name": "invoiceDateFrom", "in": "query", "description": "Include only invoices whose `invoiceDate` falls on or after this date (inclusive).", "schema": { "type": "string" } }, { "name": "invoiceDateTo", "in": "query", "description": "Include only invoices whose `invoiceDate` falls on or before this date (inclusive).", "schema": { "type": "string" } }, { "name": "invoiceStatus", "in": "query", "description": "Include only invoices with this status.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of invoices to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it. The filters must be repeated unchanged alongside it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_schemeInvoiceResponse" }, "example": { "data": [ { "invoiceReference": "string", "invoiceNumber": "string", "invoiceDate": "string", "dueDate": "string", "paidDate": "string", "invoiceStatus": "string", "grossAmount": { "amount": 0, "currencyCode": "string" }, "netAmount": { "amount": 0, "currencyCode": "string" }, "taxAmount": { "amount": 0, "currencyCode": "string" }, "paidAmount": { "amount": 0, "currencyCode": "string" } } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "Payload of ProblemDetails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/organisations/{externalId}": { "patch": { "tags": [ "Organisations" ], "summary": "Update an organisation", "description": "Applies a partial update to the organisation identified by the supplied external\nidentifier.\n\nOnly the fields present in the request body are updated; omitted fields are left\nunchanged. Fields outside the documented set are rejected with a validation error,\nas are the platform-generated `externalId`, `createdAt` and `modifiedAt`.\n\nTwo deliberate divergences from RFC 7396 JSON Merge Patch, both platform\nconventions rather than quirks of this operation:\n\n1. An explicit `null` is a no-op, not a removal. Sending `{\"email\": null}` leaves\nthe stored email untouched rather than clearing it. There is currently no way to\nclear an optional field through this endpoint.\n\n2. `director` cannot be changed here; it is accepted on create only.\n\nA body that changes nothing is rejected with `400` rather than silently\nsucceeding. An address may be partial: supplying `address` with only `city` set\nchanges the city and leaves the rest of the stored address intact.\n\n`If-Match` is accepted with the value `*`, which requires the organisation to\nexist. A concrete ETag is **not** supported - no endpoint on this platform issues\nan `ETag`, so no caller can hold a valid one, and any other value is rejected with\n`409` rather than silently ignored.\n\nThe response is `200` with an empty body: the stored record is not read back.\nRe-read with `GET` if the current record is needed.", "operationId": "Organisation-Update-Patch", "parameters": [ { "name": "externalId", "in": "path", "description": "The external organisation identifier (for example, `ORG00001234`).", "required": true, "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "Optimistic concurrency control. Only `*` is supported, requiring the organisation to exist. A concrete ETag is rejected with `409` because this API does not issue ETags.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateFeOrganisationRequest" }, "example": { "name": "string", "email": "string", "phone": "string", "address": { "addressLine1": "string", "addressLine2": "string", "city": "string", "county": "string", "postalCode": "string", "country": "string" } } } } }, "responses": { "400": { "description": "The request could not be processed due to validation failures or malformed\ninput. Field-level details are provided in the `errors` array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No organisation exists for the supplied external identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "409": { "description": "The `If-Match` precondition could not be honoured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "200": { "description": "Organisation updated. The response has no body." } } } }, "/v1/policies/{policyReference}/covered-entities/{coveredEntityReference}": { "get": { "tags": [ "Policies" ], "summary": "Retrieve the details of one covered entity on a policy", "description": "Returns the details of one covered entity on the policy, identified by\nits external reference (`CVE...`). Used to drill into a covered entity\nfrom the policy view, and by processes such as claims evaluation that\nneed the cover details of a claimant.\n\nThe covered entity is a policy administration (PAS) record. The\nresponse holds the PAS detail - entity type, member type, status,\neffective dates and the active exclusions - together with\n**references** to the related Core records:\n\n - `person.personReference` (`PER...`) - the covered person. Use it\n with `GET /v1/customers/{externalId}` in the Customer API.\n - `organisations[].organisationReference` (`ORG...`) - the\n organisations associated with the covered entity. In this version\n that is the employer of the scheme the policy belongs to. Use it\n with `GET /v1/organisations/{externalId}` in the Organisation API.\n\nPerson and organisation detail (names, contact details, addresses) is\ndeliberately **not** returned here: it is Core data and is read from\nthe Core APIs with the references above.\n\nActive and inactive covered entities are both returned; `status` says\nwhich. Only active exclusions are returned.\n\nAccess is subject to object-level authorization: the caller must hold\nan active role on the policy. The API responds `404` when the policy\nis unknown, when the caller holds no active role on it, and when the\ncovered entity is unknown or belongs to a different policy. The three\ncases are indistinguishable.", "operationId": "Policy-GetCoveredEntity-Get", "parameters": [ { "name": "policyReference", "in": "path", "description": "External policy reference, example - `POL-0000010014`.", "required": true, "schema": { "type": "string" } }, { "name": "coveredEntityReference", "in": "path", "description": "External reference of the covered entity, example - `CVE0000010037`.\nAs returned by `GET /v1/policies/{policyReference}/covered-entities`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Covered entity successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/responseEnvelope_getCoveredEntityResponse" }, "example": { "data": { "coveredEntityReference": "string", "policyReference": "string", "name": "string", "entityType": "string", "memberType": "string", "status": "string", "effectiveFrom": "string", "effectiveTo": "string", "person": { "personReference": "string" }, "schemeReference": "string", "organisations": [ { "organisationReference": "string", "relationship": "string" } ], "exclusions": [ { "name": "string", "description": "string", "exclusionType": "string", "effectiveFrom": "string", "effectiveTo": "string" } ], "createdOn": "string", "modifiedOn": "string" }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "The request did not present a valid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No policy was found for the supplied reference, the caller does not hold\nan active role on it, or the covered entity is unknown or belongs to a\ndifferent policy. The cases are deliberately indistinguishable so the\nexistence of other customers' policies is not disclosed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/policies/{policyReference}/benefit-pots": { "get": { "tags": [ "Policies" ], "summary": "List the benefit pots on a policy", "description": "Returns the benefit pots on the policy. A benefit pot is the allowance\nfor one benefit over one benefit period: the amount allocated at the\nstart of the period (`initialAllocation`), the amount claimed against\nit to date (`claimedAmount`), and what is left (`remainingBalance`),\ntogether with the period start and end dates.\n\nPots are held at benefit level. A benefit may have more than one pot\non the same policy: an **Individual** pot for each covered entity, or\na pooled **Dependants** / **Family** pot shared across the household.\n`potScope` says which, and `coveredEntity` is present only on\nIndividual pots.\n\nBy default only pots for the **current** benefit period are returned\n(`periodStatus = Active`). Pass `includeHistoricPeriods=true` to also\nreturn `Expired` and `Carried Over` periods.\n\nPass `coveredEntityReference` to return only the pots that apply to\none covered entity - for example to show one person's remaining\ncover. The result holds that covered entity's **Individual** pots\nplus the pooled pots the covered entity shares: every **Family** pot,\nand the **Dependants** pots when the covered entity's member type is\n`Dependant`. Individual pots of other covered entities are left out.\nThe covered entity must be on this policy; an unknown reference, or\none that belongs to a different policy, gives `400`.\n\nItems are ordered by `periodStart` descending (current period first),\nthen `benefit.name` ascending, then `potScope` (Individual,\nDependants, Family), then `coveredEntity.coveredEntityReference`.\n\nAccess is subject to object-level authorization: the caller must hold\nan active role on the policy. A caller with no active role receives\n`404`, indistinguishable from an unknown reference.", "operationId": "Policy-ListPolicyBenefitPots-Get", "parameters": [ { "name": "policyReference", "in": "path", "description": "External policy reference, example - `POL-0000010014`.", "required": true, "schema": { "type": "string" } }, { "name": "coveredEntityReference", "in": "query", "description": "External reference of a covered entity on this policy (`CVE...`), as\nreturned by `GET /v1/policies/{policyReference}/covered-entities`.\nWhen supplied, only the pots that apply to that covered entity are\nreturned. When omitted, all pots on the policy are returned.", "schema": { "type": "string" } }, { "name": "includeHistoricPeriods", "in": "query", "description": "When `false` (the default) only pots whose `periodStatus` is `Active`\n- the current benefit period - are returned. When `true`, pots for\n`Expired` and `Carried Over` periods are returned as well.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Benefit pots successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listResponseEnvelope_policyBenefitPotResponse" }, "example": { "data": [ { "benefit": { "benefitReference": "string", "name": "string" }, "potScope": "string", "coveredEntity": { "coveredEntityReference": "string", "name": "string" }, "periodStart": "string", "periodEnd": "string", "periodStatus": "string", "currency": "string", "initialAllocation": 0, "carryOverAmount": 0, "adjustmentAmount": 0, "claimedAmount": 0, "clawbackAmount": 0, "remainingBalance": 0, "sharedPoolPerPersonCap": 0, "lastUpdatedOn": "string" } ], "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation, or the supplied\n`coveredEntityReference` is not a covered entity on this policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "The request did not present a valid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No policy was found for the supplied reference, or the caller does not\nhold an active role on it. The two cases are deliberately\nindistinguishable so the existence of other customers' policies is not\ndisclosed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/policies/{policyReference}/claims/duplicate-check": { "get": { "tags": [ "Claims" ], "summary": "Check for duplicate claim line items on a policy", "description": "Searches the claims on a policy for line items matching the supplied details, so a duplicate can be found before it is paid. Supply the claimant and at least one of the benefit, claim date, benefit date and cost. Every criterion must match exactly. Line items on claims of every status are returned; the caller decides which matter. Read-only. At most 50 matches are returned, with a RESULT_TRUNCATED warning when more exist.", "operationId": "checkDuplicateClaims", "parameters": [ { "name": "policyReference", "in": "path", "description": "Reference of the policy to search, for example POL-0000010031.", "required": true, "schema": { "type": "string" } }, { "name": "claimantReference", "in": "query", "description": "Covered entity reference of the claimant. Must be a covered entity on this policy.", "required": true, "schema": { "type": "string" } }, { "name": "benefitReference", "in": "query", "description": "Benefit of the line item. Must exist. Exact match.", "schema": { "type": "string" } }, { "name": "claimDate", "in": "query", "description": "Claim date of the line item, as YYYY-MM-DD. Exact match.", "schema": { "type": "string" } }, { "name": "benefitDate", "in": "query", "description": "Date the benefit is claimed for, as YYYY-MM-DD. Exact match.", "schema": { "type": "string" } }, { "name": "totalCost", "in": "query", "description": "Cost of the line item, to at most 2 decimal places. Exact match.", "schema": { "type": "number", "format": "double" } }, { "name": "excludeClaimLineItemReference", "in": "query", "description": "Line item being examined. It is left out of the result so it cannot match itself.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search completed. data is empty when no match was found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listResponseEnvelope_duplicateClaimMatchResponse" }, "example": { "data": [ { "claimReference": "string", "claimStatus": "string", "claimSubStatus": "string", "rejectionReason": "string", "claimCreatedAt": "string", "claimLineItemReference": "string", "lineStatus": "string", "claimDate": "string", "benefitDate": "string", "totalCost": 0, "totalAmountCovered": 0, "invoiceReference": "string", "benefit": { "benefitReference": "string", "name": "string" }, "claimant": { "coveredEntityReference": "string", "name": "string" } } ], "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation, or the claimant is not on the policy, or the benefit does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "401": { "description": "The request did not present a valid authentication token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No policy was found for the supplied reference, or the caller cannot see it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } }, "/v1/organisations/{externalId}/events": { "get": { "tags": [ "Events" ], "summary": "List events for an organisation", "description": "Returns the events attached to the organisation, most recent first. An event\nis a generic record that can be attached to one or more people, organisations\nor policies through event associations; this endpoint returns the events with\nan active association to the organisation identified in the path. Use the\n`type` query parameter to filter to a single event type.\n\nThe caller must hold a current portal-user grant to the organisation. An\norganisation that does not exist and an organisation the caller is not\ngranted both return `404`, so organisation existence is not disclosed.", "operationId": "Organisation-ListEvents-Get", "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Include only events of this type. A value outside the enum gives `400` with the field code `INVALID_ENUM_VALUE`.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Number of events to return per page, between 1 and 5000. Optional on the first request, where it defaults to 25. Required whenever 'nextPage' is supplied, and must repeat the value used for the first request - the page size cannot change part-way through a paging sequence.", "schema": { "type": "integer", "format": "int32" } }, { "name": "nextPage", "in": "query", "description": "Opaque cursor taken from 'pagination.nextPage' of the previous response. Omit to retrieve the first page; echo the value verbatim and do not parse it.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of events attached to the organisation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pagedResponseEnvelope_organisationEventResponse" }, "example": { "data": [ { "externalId": "string", "name": "string", "eventType": "string", "description": "string", "effectiveDate": "string", "visibleOnPortals": true, "personExternalId": "string", "organisationExternalId": "string", "createdAt": "string", "modifiedAt": "string" } ], "pagination": { "nextPage": "string", "pageSize": 0, "totalItems": 0 }, "meta": { "requestId": "string", "timestamp": "string", "apiVersion": "string", "warnings": [ { "code": "string", "message": "string" } ] } } } } }, "400": { "description": "The request was malformed or failed validation. Field-level details are\nprovided in the `errors` array when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "403": { "description": "The caller is authenticated but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "404": { "description": "No resource exists for the supplied identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "410": { "description": "The resource exists but has been soft-deleted. No data is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "500": { "description": "An unhandled server-side error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } }, "503": { "description": "A downstream dependency is temporarily\nunavailable. The caller should retry after a short delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/problemDetails" }, "example": { "type": "string", "title": "string", "status": 0, "detail": "string", "instance": "string", "code": "string", "errors": [ { "field": "string", "code": "string", "message": "string" } ] } } } } } } } }, "components": { "schemas": { "addSchemeMemberRequest": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "employeeNumber": { "type": "string" }, "email": { "type": "string" }, "effectiveDate": { "type": "string", "description": "The enrolment (effective) date for the member." }, "memberType": { "type": "string" } } }, "choiceListSummaryResponse": { "type": "object", "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "choiceCount": { "type": "integer", "description": "Number of choices in this list.", "format": "int32" } } }, "choiceResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable SCREAMING_SNAKE identifier for the choice. This is the value\nother API endpoints accept and return for enum-typed fields." }, "label": { "type": "string", "description": "Human-readable display name (English in v1)." } } }, "claim": { "type": "object", "properties": { "claimReference": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "rejectionReason": { "type": "string", "description": "Reason the claim was rejected. Set only when status is rejected." }, "payoutBasis": { "type": "string" }, "totalAmountClaimed": { "type": "number", "format": "double", "nullable": true }, "policyReference": { "type": "string" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/claimLineItem" } } } }, "claimLineItem": { "type": "object", "properties": { "claimLineItemReference": { "type": "string" }, "name": { "type": "string" }, "lineStatus": { "type": "string" }, "claimDate": { "type": "string" }, "benefitDate": { "type": "string", "description": "Date the benefit is claimed for (`YYYY-MM-DD`). Depending on the benefit this is the treatment date, the discharge date, or the\nbirth / adoption date. `benefitDate` replaces the earlier\n\"treatment date\" (`treatmentDate`) concept. Null on line items\ncreated before this field was captured." }, "totalCost": { "type": "number", "format": "double", "nullable": true }, "totalAmountCovered": { "type": "number", "format": "double", "nullable": true }, "excessApplied": { "type": "number", "format": "double", "nullable": true }, "copayApplied": { "type": "number", "format": "double", "nullable": true }, "invoiceReference": { "type": "string" }, "externalId": { "type": "string" }, "benefit": { "$ref": "#/components/schemas/claimLineItemBenefit" }, "claimant": { "$ref": "#/components/schemas/claimLineItemClaimant" } } }, "claimLineItemBenefit": { "type": "object", "properties": { "benefitReference": { "type": "string" }, "name": { "type": "string" } } }, "claimLineItemClaimant": { "type": "object", "properties": { "coveredEntityReference": { "type": "string", "description": "Reference of the covered entity (claimant)." }, "name": { "type": "string", "description": "Name of the covered entity (claimant)." } } }, "coveredEntityExclusionResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Short name of the exclusion." }, "description": { "type": "string", "description": "Detail of the exclusion. Omitted when not set." }, "exclusionType": { "type": "string", "description": "Type of exclusion." }, "effectiveFrom": { "type": "string", "description": "First day the exclusion applies. Omitted when not set." }, "effectiveTo": { "type": "string", "description": "Last day the exclusion applies. Omitted when open-ended." } } }, "coveredEntityOrganisationResponse": { "type": "object", "properties": { "organisationReference": { "type": "string", "description": "Public-facing organisation reference (`ORG...`). Use it as\n`{externalId}` on `GET /v1/organisations/{externalId}` in the Organisation API." }, "relationship": { "type": "string", "description": "How the organisation is associated with the covered entity.\n`Scheme Employer` - the employer of the scheme the policy belongs to." } } }, "coveredEntityPersonReferenceResponse": { "type": "object", "properties": { "personReference": { "type": "string", "description": "Public-facing person reference (`PER...`). Use it as\n`{externalId}` on `GET /v1/customers/{externalId}` in the Customer API to read the person's details." } }, "description": "Reference to the Core person record of the covered person. Present\nwhen the covered entity is linked to a person." }, "coveredEntityPersonResponse": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Given name." }, "lastName": { "type": "string", "description": "Family name." }, "fullName": { "type": "string", "description": "Full name." }, "email": { "type": "string", "description": "Email address." }, "dateOfBirth": { "type": "string", "description": "Date of birth." } }, "description": "Present when the covered entity is a person (`entityType = Person`)." }, "coveredEntityResponse": { "type": "object", "properties": { "coveredEntityReference": { "type": "string", "description": "External reference of the covered entity (`CVE...`), sent as\n`claimantReference` when creating a claim line item." }, "name": { "type": "string", "description": "Display name." }, "entityType": { "type": "string" }, "memberType": { "type": "string" }, "status": { "type": "string", "description": "Lifecycle status of the covered entity." }, "effectiveFrom": { "type": "string", "description": "Date from which the cover is effective." }, "effectiveTo": { "type": "string", "description": "Date until which the cover is effective." }, "person": { "$ref": "#/components/schemas/coveredEntityPersonResponse" } } }, "createClaimLineItemRequest": { "type": "object", "properties": { "benefitReference": { "type": "string", "description": "Reference of the selected benefit, from the mapped benefit dropdown" }, "claimantReference": { "type": "string", "description": "Reference of the covered entity (claimant) this line item is for,\nselected from the policy's covered entities." }, "claimDate": { "type": "string" }, "benefitDate": { "type": "string", "description": "Date the benefit is claimed for (`YYYY-MM-DD`). Depending on the benefit this is the treatment date, the discharge date, or the\nbirth / adoption date. `benefitDate` replaces the earlier\n\"treatment date\" (`treatmentDate`) concept: there is one date\nfield for every benefit type, and no separate treatment date.\nDifferent from `claimDate`, which is the date of the claim line.\nUsed by the duplicate claim check." }, "totalCost": { "type": "number", "description": "Amount claimed for this line, supplied by the caller. Required, positive money value. Used for the benefit-pot balance check (compared against the pot's remaining balance to accept or reject the claim). This is the amount claimed, not the payable amount — totalAmountCovered (after cover limits/excess/co-pay) is derived server-side in a later iteration and is out of scope. Trusted here because the operation only accepts/rejects and moves no money.", "format": "double" }, "invoiceReference": { "type": "string" } } }, "createClaimRequest": { "type": "object", "properties": { "name": { "type": "string" }, "totalAmountClaimed": { "type": "number", "format": "double", "nullable": true }, "payoutBasis": { "type": "string" }, "externalId": { "type": "string" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/createClaimLineItemRequest" } } } }, "createFeLocationRequest": { "type": "object", "properties": { "name": { "type": "string" }, "organisationExternalId": { "type": "string", "description": "External ID of the organisation this location belongs to." }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "addressLine3": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" }, "locationCategory": { "type": "string" }, "latitude": { "type": "number", "format": "double", "nullable": true }, "longitude": { "type": "number", "format": "double", "nullable": true }, "emailAddress": { "type": "string" }, "phoneNumber": { "type": "string" }, "notes": { "type": "string" } } }, "createFeLocationResponse": { "type": "object", "properties": { "externalId": { "type": "string" } } }, "createFeOrganisationAddressRequest": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "postalCode": { "type": "string", "description": "Postal code in the country's native format. UK postcodes follow the standard PAF format." }, "country": { "type": "string", "description": "Country name. Will eventually be constrained to ISO 3166 alpha-2 codes." } } }, "createFeOrganisationDirectorRequest": { "type": "object", "properties": { "personExternalId": { "type": "string", "description": "External ID of the person who is a director of this organisation." }, "effectiveFrom": { "type": "string" }, "effectiveTo": { "type": "string" }, "notes": { "type": "string" } } }, "createFeOrganisationRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Legal entity name (typically as registered with Companies House)." }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "$ref": "#/components/schemas/createFeOrganisationAddressRequest" }, "director": { "$ref": "#/components/schemas/createFeOrganisationDirectorRequest" } } }, "createFeOrganisationResponse": { "type": "object", "properties": { "externalId": { "type": "string", "description": "Stable external identifier. Auto-generated on create." } } }, "createFePolicyAddressRequest": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "line3": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "countryCode": { "type": "string" } } }, "createFePolicyContactRequest": { "type": "object", "properties": { "emailAddress": { "type": "string", "description": "Email address of the contact." }, "phoneMobile": { "type": "string" }, "phoneLandline": { "type": "string" }, "address": { "$ref": "#/components/schemas/createFePolicyAddressRequest" } } }, "createFePolicyDirectDebitRequest": { "type": "object", "properties": { "collectionDay": { "type": "integer", "description": "Day of the month on which Direct Debit collection will occur.", "format": "int32" } } }, "createFePolicyEventChangeRequest": { "type": "object", "properties": { "previousStatus": { "type": "string" }, "newStatus": { "type": "string" }, "previousFundingType": { "type": "string" }, "newFundingType": { "type": "string" }, "previousMemberType": { "type": "string" }, "newMemberType": { "type": "string" }, "previousProductVersionLevelId": { "type": "string" }, "newProductVersionLevelId": { "type": "string" }, "previousPremium": { "type": "string" }, "newPremium": { "type": "string" }, "currency": { "type": "string" } } }, "createFePolicyEventChangeResponse": { "type": "object", "properties": { "previousStatus": { "type": "string" }, "newStatus": { "type": "string" }, "previousFundingType": { "type": "string" }, "newFundingType": { "type": "string" }, "previousMemberType": { "type": "string" }, "newMemberType": { "type": "string" }, "previousProductVersionLevelId": { "type": "string" }, "newProductVersionLevelId": { "type": "string" }, "previousPremium": { "type": "string", "description": "Previous gross premium as a numeric string." }, "newPremium": { "type": "string", "description": "New gross premium as a numeric string." }, "currency": { "type": "string", "description": "ISO 4217 currency code for the premium amounts. Required when a\npremium value is supplied." } }, "description": "Before / after detail, echoed when supplied on the request.\nOmitted entirely when no transition detail was provided." }, "createFePolicyEventRequest": { "type": "object", "properties": { "eventType": { "type": "string" }, "eventDate": { "type": "string", "description": "Timestamp the event occurred (ISO 8601 UTC)." }, "effectiveDate": { "type": "string", "description": "Business-effective date of the event (`YYYY-MM-DD`). Persisted at\nmidnight UTC." }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "externalId": { "type": "string" }, "change": { "$ref": "#/components/schemas/createFePolicyEventChangeRequest" } } }, "createFePolicyEventResponse": { "type": "object", "properties": { "eventId": { "type": "string", "description": "System identifier of the event." }, "policyReference": { "type": "string", "description": "Public reference of the parent policy, echoed from the path." }, "policyId": { "type": "string", "description": "System identifier of the parent policy." }, "eventType": { "type": "string" }, "name": { "type": "string", "description": "Short event name." }, "description": { "type": "string", "description": "Free-text detail for the event." }, "eventDate": { "type": "string", "description": "Timestamp the event occurred." }, "effectiveDate": { "type": "string", "description": "Business-effective date of the event." }, "status": { "type": "string" }, "initiatedBy": { "type": "string" }, "performedBy": { "type": "string" }, "change": { "$ref": "#/components/schemas/createFePolicyEventChangeResponse" }, "createdOn": { "type": "string", "description": "Timestamp the event was created." } } }, "createFePolicyHolderRequest": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/createFePolicyPersonRequest" }, "contact": { "$ref": "#/components/schemas/createFePolicyContactRequest" }, "directDebit": { "$ref": "#/components/schemas/createFePolicyDirectDebitRequest" } } }, "createFePolicyPersonRequest": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Given name." }, "lastName": { "type": "string", "description": "Family name." }, "dateOfBirth": { "type": "string", "description": "Date of birth." } } }, "createFePolicyPricingRequest": { "type": "object", "properties": { "grossPremium": { "type": "number", "description": "Gross premium amount supplied by the caller. Persisted as-is. No\nrecalculation is performed at this stage.", "format": "double" }, "currency": { "type": "string" }, "paymentFrequency": { "type": "string" } } }, "createFePolicyProductRequest": { "type": "object", "properties": { "productReference": { "type": "string", "description": "External product reference. Resolved to the matching product at the\nAPI layer." }, "brandReference": { "type": "string", "description": "External brand reference. Resolved to the matching brand at the\nAPI layer." }, "coverLevel": { "type": "string" }, "productVersion": { "type": "string", "description": "Specific product version reference. When null the API resolves\nto the currently-active version of the product." } } }, "createFePolicyRequest": { "type": "object", "properties": { "startDate": { "type": "string", "description": "Requested policy live date. Recorded as the policy's live date and\nused as the effective-from date for the policy holder role, covered\nentity, and audit event." }, "fundingType": { "type": "string" }, "product": { "$ref": "#/components/schemas/createFePolicyProductRequest" }, "pricing": { "$ref": "#/components/schemas/createFePolicyPricingRequest" }, "policyHolder": { "$ref": "#/components/schemas/createFePolicyHolderRequest" } } }, "createFePolicyResponse": { "type": "object", "properties": { "policyReference": { "type": "string", "description": "Public-facing policy reference, suitable for display to the\ncustomer and for use in subsequent API calls." }, "contactExternalId": { "type": "string", "description": "Public-facing customer reference." }, "status": { "type": "string" }, "liveDate": { "type": "string", "description": "The policy's live date, echoed from the request." } } }, "duplicateClaimBenefitResponse": { "type": "object", "properties": { "benefitReference": { "type": "string" }, "name": { "type": "string" } } }, "duplicateClaimClaimantResponse": { "type": "object", "properties": { "coveredEntityReference": { "type": "string" }, "name": { "type": "string" } } }, "duplicateClaimMatchResponse": { "type": "object", "properties": { "claimReference": { "type": "string" }, "claimStatus": { "type": "string" }, "claimSubStatus": { "type": "string" }, "rejectionReason": { "type": "string" }, "claimCreatedAt": { "type": "string" }, "claimLineItemReference": { "type": "string" }, "lineStatus": { "type": "string" }, "claimDate": { "type": "string" }, "benefitDate": { "type": "string" }, "totalCost": { "type": "number", "format": "double", "nullable": true }, "totalAmountCovered": { "type": "number", "format": "double", "nullable": true }, "invoiceReference": { "type": "string" }, "benefit": { "$ref": "#/components/schemas/duplicateClaimBenefitResponse" }, "claimant": { "$ref": "#/components/schemas/duplicateClaimClaimantResponse" } } }, "getChoiceListResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "camelCase identifier used in the API path." }, "scope": { "type": "string", "description": "Whether the underlying choice set is global (shared across multiple\nrecord types) or attribute-scoped (bound to a single field)." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/choiceResponse" }, "description": "The choices in this list, in catalogue-defined order." }, "catalogueVersion": { "type": "string", "description": "Version of the catalogue payload at the time the response was generated." }, "catalogueGeneratedAt": { "type": "string", "description": "Timestamp the catalogue source was generated (ISO 8601 UTC).", "format": "date-time" } } }, "getCoveredEntityResponse": { "type": "object", "properties": { "coveredEntityReference": { "type": "string", "description": "External reference of the covered entity (`CVE...`)." }, "policyReference": { "type": "string", "description": "Public reference of the policy the covered entity is on." }, "name": { "type": "string", "description": "Display name of the covered entity. Omitted when not set." }, "entityType": { "type": "string", "description": "Type of covered entity." }, "memberType": { "type": "string", "description": "Member type / relationship of the covered entity." }, "status": { "type": "string", "description": "Lifecycle status of the covered entity." }, "effectiveFrom": { "type": "string", "description": "First day of cover. Omitted when not set." }, "effectiveTo": { "type": "string", "description": "Last day of cover. Omitted when the cover is open-ended." }, "person": { "$ref": "#/components/schemas/coveredEntityPersonReferenceResponse" }, "schemeReference": { "type": "string", "description": "Reference of the scheme the policy belongs to (`SCH...`). Omitted\nwhen the policy is not on a scheme." }, "organisations": { "type": "array", "items": { "$ref": "#/components/schemas/coveredEntityOrganisationResponse" }, "description": "Organisations associated with the covered entity. Empty when\nthere are none." }, "exclusions": { "type": "array", "items": { "$ref": "#/components/schemas/coveredEntityExclusionResponse" }, "description": "Active exclusions recorded against the covered entity, ordered by\n`effectiveFrom` ascending. Empty when there are none." }, "createdOn": { "type": "string", "description": "Timestamp the covered entity was created." }, "modifiedOn": { "type": "string", "description": "Timestamp the covered entity was last modified." } } }, "getFeCustomerPolicyHolderResponse": { "type": "object", "properties": { "contactExternalId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "fullName": { "type": "string", "description": "Concatenated full name. Provided for convenience; consumers requiring\nstrict structure should prefer `firstName` and `lastName`." } } }, "getFeCustomerPolicyPricingResponse": { "type": "object", "properties": { "grossPremium": { "type": "string", "description": "Gross premium expressed as a numeric string to preserve precision\n(never a floating-point number), per the Sovereign Health Care API\nDesign Standards. Paired with `currency`." }, "currency": { "type": "string", "description": "ISO 4217 currency code." }, "paymentFrequency": { "type": "string", "description": "Payment frequency, normalised to an enum." } } }, "getFeCustomerPolicyProductResponse": { "type": "object", "properties": { "productReference": { "type": "string", "description": "External identifier of the product." }, "productName": { "type": "string", "description": "Display name of the product." }, "productVersion": { "type": "string", "description": "Display name of the product version. Omitted when not set." }, "productVersionReference": { "type": "string", "description": "External identifier of the product version. Omitted when not set." }, "coverLevel": { "type": "string", "description": "Cover level, derived at the API boundary (for example, level `5`\nbecomes `LEVEL_5`)." }, "coverLevelName": { "type": "string", "description": "Display name of the cover level. Omitted when not set." } } }, "getFeCustomerPolicyResponse": { "type": "object", "properties": { "policyId": { "type": "string", "description": "Record identifier for the policy (lowercase, hyphenated)." }, "policyReference": { "type": "string" }, "name": { "type": "string", "description": "Display name of the policy." }, "status": { "type": "string", "description": "Current policy status, normalised at the API boundary." }, "customerRole": { "type": "string", "description": "The role the customer holds on this policy that caused it to be\nreturned. For this endpoint the value is always `POLICY_HOLDER`; the\nfield is included for forward compatibility should additional role\nviews be introduced." }, "liveDate": { "type": "string", "description": "Date the policy goes (or went) live, in `YYYY-MM-DD` format. Omitted\nwhen not set." }, "product": { "$ref": "#/components/schemas/getFeCustomerPolicyProductResponse" }, "pricing": { "$ref": "#/components/schemas/getFeCustomerPolicyPricingResponse" }, "policyHolder": { "$ref": "#/components/schemas/getFeCustomerPolicyHolderResponse" }, "createdOn": { "type": "string", "description": "Record creation timestamp (ISO 8601 UTC)." }, "modifiedOn": { "type": "string", "description": "Record last-modified timestamp (ISO 8601 UTC). Omitted when the record\nhas not been modified since creation." } } }, "getFePolicyAddressResponse": { "type": "object", "properties": { "line1": { "type": "string", "description": "First line of the address." }, "line2": { "type": "string", "description": "Second line of the address." }, "line3": { "type": "string", "description": "Third line of the address." }, "city": { "type": "string", "description": "City or town." }, "postalCode": { "type": "string", "description": "Postal code." }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (resolution from / to country name\nperformed by the integration layer)." }, "verified": { "type": "boolean", "description": "Whether the address has been verified by an address-lookup\nservice.\n\n**Storage location TBD** - the field is accepted but the\npersistence target is not yet finalised." }, "verificationId": { "type": "string", "description": "Identifier of the address-verification result, where the address\nhas been verified.\n\n**Storage location TBD** - see `verified`." } } }, "getFePolicyConsentsResponse": { "type": "object", "properties": { "termsAcceptedOn": { "type": "string", "description": "Timestamp at which the customer accepted the terms." }, "ipidAcknowledgedOn": { "type": "string", "description": "Timestamp at which the customer acknowledged the IPID." }, "marketingOptIn": { "type": "boolean", "description": "Whether the customer has opted in to marketing communications." } } }, "getFePolicyContactResponse": { "type": "object", "properties": { "emailAddress": { "type": "string", "description": "Email address of the contact." }, "phoneMobile": { "type": "string", "description": "Mobile phone number in E.164 form." }, "phoneLandline": { "type": "string", "description": "Landline phone number in E.164 form." }, "address": { "$ref": "#/components/schemas/getFePolicyAddressResponse" } } }, "getFePolicyCoveredLifeResponse": { "type": "object", "properties": { "coveredEntityReference": { "type": "string", "description": "External reference (`CVE...`) of the covered entity record of this\nadditional adult. Use it with\n`GET /v1/policies/{policyReference}/covered-entities/{coveredEntityReference}`." }, "contactId": { "type": "string" }, "contactExternalId": { "type": "string" }, "person": { "$ref": "#/components/schemas/getFePolicyPersonResponse" } } }, "getFePolicyDirectDebitResponse": { "type": "object", "properties": { "bankName": { "type": "string" }, "accountHolderName": { "type": "string" }, "sortCode": { "type": "string" }, "accountNumber": { "type": "string" }, "collectionDay": { "type": "integer", "description": "Day of the month on which Direct Debit collection will occur.", "format": "int32" }, "verified": { "type": "boolean", "description": "Whether the bank details have been verified by an account-lookup\nservice." }, "mandateAcceptedAt": { "type": "string", "description": "Timestamp at which the customer accepted the DD mandate." } } }, "getFePolicyEventResponse": { "type": "object", "properties": { "eventType": { "type": "string" }, "name": { "type": "string", "description": "Short event name." }, "description": { "type": "string", "description": "Free-text detail for the event." }, "eventDate": { "type": "string", "description": "Timestamp the event occurred." }, "effectiveDate": { "type": "string", "description": "Business-effective date of the event." } } }, "getFePolicyHolderResponse": { "type": "object", "properties": { "coveredEntityReference": { "type": "string", "description": "External reference (`CVE...`) of the covered entity that covers the\npolicy holder on this policy. Omitted when the policy holder is\nnot a covered entity on the policy. Use it with\n`GET /v1/policies/{policyReference}/covered-entities/{coveredEntityReference}`." }, "contactId": { "type": "string", "description": "System identifier of the customer (contact) record." }, "contactExternalId": { "type": "string", "description": "Public-facing customer reference." }, "person": { "$ref": "#/components/schemas/getFePolicyPersonResponse" }, "contact": { "$ref": "#/components/schemas/getFePolicyContactResponse" }, "consents": { "$ref": "#/components/schemas/getFePolicyConsentsResponse" } } }, "getFePolicyPayerResponse": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/getFePolicyPersonResponse" }, "contact": { "$ref": "#/components/schemas/getFePolicyContactResponse" }, "directDebit": { "$ref": "#/components/schemas/getFePolicyDirectDebitResponse" } } }, "getFePolicyPersonResponse": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Given name." }, "lastName": { "type": "string", "description": "Family name." }, "dateOfBirth": { "type": "string", "description": "Date of birth." } } }, "getFePolicyPricingResponse": { "type": "object", "properties": { "source": { "type": "string" }, "grossPremium": { "type": "string", "description": "Gross premium amount persisted on the policy." }, "grossPremiumFormatted": { "type": "string", "description": "Currency-formatted gross premium. Derived by the integration layer." }, "currency": { "type": "string" }, "paymentFrequency": { "type": "string" } } }, "getFePolicyProductResponse": { "type": "object", "properties": { "productReference": { "type": "string", "description": "External product reference. Resolved to the matching product at the\nAPI layer." }, "brandReference": { "type": "string", "description": "External brand reference. Resolved to the matching brand at the\nAPI layer." }, "coverLevel": { "type": "string" }, "productVersion": { "type": "string", "description": "Specific product version reference. When null the API resolves\nto the currently-active version of the product." } } }, "getFePolicyProviderResponse": { "type": "object", "properties": { "providerId": { "type": "string", "description": "System identifier of the provider, as held on the policy." }, "providerReference": { "type": "string", "description": "Public-facing provider reference (`PRV...`), from the Core provider record." }, "name": { "type": "string", "description": "Display name of the provider, from the Core provider record." } } }, "getFePolicyResponse": { "type": "object", "properties": { "policyId": { "type": "string", "description": "System identifier of the policy." }, "policyReference": { "type": "string", "description": "Public-facing policy reference." }, "contactId": { "type": "string", "description": "System identifier of the customer (contact) acting as policy\nholder." }, "contactExternalId": { "type": "string", "description": "Public-facing customer reference." }, "name": { "type": "string", "description": "Display name of the policy, composed at create time." }, "status": { "type": "string" }, "channel": { "type": "string" }, "quoteReference": { "type": "string", "description": "Reference to the originating quote, where applicable." }, "liveDate": { "type": "string", "description": "The policy's live date." }, "fundingType": { "type": "string" }, "provider": { "$ref": "#/components/schemas/getFePolicyProviderResponse" }, "product": { "$ref": "#/components/schemas/getFePolicyProductResponse" }, "pricing": { "$ref": "#/components/schemas/getFePolicyPricingResponse" }, "policyHolder": { "$ref": "#/components/schemas/getFePolicyHolderResponse" }, "payer": { "$ref": "#/components/schemas/getFePolicyPayerResponse" }, "additionalAdults": { "type": "array", "items": { "$ref": "#/components/schemas/getFePolicyCoveredLifeResponse" }, "description": "Additional adult covered entities on the policy. Empty in the\ncurrent iteration (see request schema)." }, "dependants": { "type": "array", "items": { "$ref": "#/components/schemas/getFePolicyCoveredLifeResponse" }, "description": "Dependant covered entities on the policy. Empty in the current\niteration (see request schema)." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/getFePolicyEventResponse" }, "description": "Audit events recorded against the policy. At creation the array\ncontains a single `Policy Created` event." }, "referralCode": { "type": "string" }, "referringPolicyReference": { "type": "string" }, "createdOn": { "type": "string", "description": "Timestamp the policy was created." }, "modifiedOn": { "type": "string", "description": "Timestamp the policy was last modified." } } }, "getFeProductProviderResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Provider name." }, "description": { "type": "string", "description": "Free-text description of the provider." }, "settings": { "type": "array", "items": { "$ref": "#/components/schemas/getFeProductProviderSettingResponse" }, "description": "Provider settings active for this provider." } } }, "getFeProductProviderSettingResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Setting display name." }, "value": { "type": "string", "description": "Setting value, coerced to its native type (number / boolean /\nstring) by the integration layer where unambiguous." } } }, "getFeProductResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "External product reference that uniquely identifies the product." }, "name": { "type": "string", "description": "Product name." }, "description": { "type": "string", "description": "Free-text description of the product." }, "status": { "type": "string" }, "provider": { "$ref": "#/components/schemas/getFeProductProviderResponse" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/getFeProductVersionResponse" }, "description": "All versions of the product, ordered by version number (descending)." } } }, "getFeProductVersionBenefitCoverageResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Coverage rule name." }, "coveredEntityType": { "type": "string", "description": "The type of entity this coverage rule applies to." }, "coverageType": { "type": "string", "description": "How the benefit is settled." }, "status": { "type": "string" }, "qualifyingPeriodMonths": { "type": "integer", "description": "Qualifying period, in months, before the benefit can be claimed.", "format": "int32" }, "benefitPeriodMonths": { "type": "integer", "description": "Benefit period, in months.", "format": "int32" }, "benefitPeriodBasis": { "type": "string", "description": "Whether the benefit period is fixed or rolling." }, "excessType": { "type": "string", "description": "How any excess is applied to a claim." }, "excessValue": { "type": "number", "description": "Excess amount applied to a claim.", "format": "double" }, "limitType": { "type": "string", "description": "How the benefit limit is applied." }, "limitValue": { "type": "number", "description": "Monetary value of the benefit limit.", "format": "double" }, "maxReimbursementValue": { "type": "number", "description": "Maximum reimbursement payable under this coverage rule.", "format": "double" }, "maxPaybackType": { "type": "string", "description": "How the maximum payback is calculated." }, "maxPaybackValue": { "type": "number", "description": "Value used when calculating the maximum payback.", "format": "double" }, "potAllocation": { "type": "string", "description": "How a shared benefit pot is allocated." }, "claimBasis": { "type": "string", "description": "The basis on which claims are counted against this coverage." } } }, "getFeProductVersionBenefitResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Product version benefit name." }, "benefit": { "type": "string", "description": "Underlying benefit name." }, "status": { "type": "string" }, "isCore": { "type": "boolean", "description": "Indicates whether this is a core benefit included in the product version." }, "coveredEntityType": { "type": "string", "description": "The type of entity the benefit covers." }, "coverage": { "type": "array", "items": { "$ref": "#/components/schemas/getFeProductVersionBenefitCoverageResponse" }, "description": "Coverage rules for this benefit." } } }, "getFeProductVersionLevelBenefitResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Level benefit name." }, "benefit": { "type": "string", "description": "Underlying benefit name." }, "status": { "type": "string" }, "qualifyingPeriod": { "type": "string", "description": "Qualifying period, in months, before this benefit can be claimed at this level." }, "minReimbursementValue": { "type": "number", "description": "Minimum reimbursement payable for this benefit at this level.", "format": "double" }, "maxReimbursementValue": { "type": "number", "description": "Maximum reimbursement payable for this benefit at this level.", "format": "double" }, "maxPaybackType": { "type": "string", "description": "How the maximum payback is calculated." }, "maxPaybackValue": { "type": "number", "description": "Value used when calculating the maximum payback.", "format": "double" }, "dependentMinReimbursementValue": { "type": "number", "description": "Minimum reimbursement payable for a dependant.", "format": "double" }, "dependentMaxReimbursementValue": { "type": "number", "description": "Maximum reimbursement payable for a dependant.", "format": "double" }, "additionalAdultMinReimbursementValue": { "type": "number", "description": "Minimum reimbursement payable for an additional adult.", "format": "double" }, "additionalAdultMaxReimbursementValue": { "type": "number", "description": "Maximum reimbursement payable for an additional adult.", "format": "double" }, "familySharedPoolValue": { "type": "number", "description": "Value of the shared benefit pool available to the family.", "format": "double" }, "dependentSharedPoolValue": { "type": "number", "description": "Value of the shared benefit pool available to dependants.", "format": "double" } } }, "getFeProductVersionLevelPriceResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "Pricing row name." }, "memberType": { "type": "string", "description": "Member composition the price applies to." }, "amount": { "type": "number", "description": "Pricing amount, in pounds sterling.", "format": "double" }, "effectiveFrom": { "type": "string", "description": "Date from which this price is effective." }, "approvedOn": { "type": "string", "description": "Date on which this price was approved." }, "effectiveTo": { "type": "string", "description": "Date until which this price is effective." }, "status": { "type": "string" }, "rateType": { "type": "string", "description": "The type of rate used for this price." }, "paymentFrequency": { "type": "string", "description": "Frequency at which the price is payable." }, "formula": { "type": "string", "description": "Pricing formula expression, when the rate type is formula-based." } } }, "getFeProductVersionLevelResponse": { "type": "object", "properties": { "level": { "type": "integer", "description": "Numeric level identifier within the product version.", "format": "int32" }, "name": { "type": "string", "description": "Level name." }, "description": { "type": "string", "description": "Free-text description of the level." }, "status": { "type": "string" }, "pricing": { "type": "array", "items": { "$ref": "#/components/schemas/getFeProductVersionLevelPriceResponse" }, "description": "Pricing rows for this level." }, "benefits": { "type": "array", "items": { "$ref": "#/components/schemas/getFeProductVersionLevelBenefitResponse" }, "description": "Level-specific benefit limits." } } }, "getFeProductVersionResponse": { "type": "object", "properties": { "number": { "type": "string", "description": "Version number." }, "effectiveFrom": { "type": "string", "description": "Date from which this product version is effective." }, "effectiveTo": { "type": "string", "description": "Date until which this product version is effective." }, "name": { "type": "string", "description": "Product version name." }, "status": { "type": "string", "description": "Lifecycle status of the product version." }, "pricingMethod": { "type": "string", "description": "Method used to price this product version." }, "dependentHandling": { "type": "string", "description": "How dependants are handled on policies for this product version." }, "maxDependentAge": { "type": "integer", "description": "Maximum age permitted for a dependant.", "format": "int32" }, "additionalAdultHandling": { "type": "string", "description": "How additional adults are handled on policies for this product version." }, "maxAdditionalAdults": { "type": "integer", "description": "Maximum number of additional adults permitted.", "format": "int32" }, "benefits": { "type": "array", "items": { "$ref": "#/components/schemas/getFeProductVersionBenefitResponse" }, "description": "Benefits defined at the version level." }, "levels": { "type": "array", "items": { "$ref": "#/components/schemas/getFeProductVersionLevelResponse" }, "description": "Levels defined for this version, ordered ascending by `level`." } } }, "getPolicyClaimResponse": { "type": "object", "properties": { "claimReference": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "subStatus": { "type": "string" }, "totalAmountClaimed": { "type": "number", "format": "double", "nullable": true }, "totalAmountCovered": { "type": "number", "format": "double", "nullable": true }, "lineItemCount": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "healthReportEntryResponse": { "type": "object", "properties": { "status": { "type": "string" }, "description": { "type": "string" }, "data": { "type": "object", "additionalProperties": { "type": "object" } } } }, "healthReportResponse": { "type": "object", "properties": { "status": { "type": "string" }, "entries": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/healthReportEntryResponse" } } } }, "listChoiceListsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/choiceListSummaryResponse" } }, "catalogueVersion": { "type": "string", "description": "Version of the catalogue payload at the time the response was generated." }, "catalogueGeneratedAt": { "type": "string", "description": "Timestamp the catalogue source was generated (ISO 8601 UTC).", "format": "date-time" } } }, "listCoveredEntitiesResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/coveredEntityResponse" } } } }, "listProductVersionBenefitsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/productVersionBenefitSummaryResponse" } } } }, "listResponseEnvelope_duplicateClaimMatchResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/duplicateClaimMatchResponse" } }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "listResponseEnvelope_policyBenefitPotResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/policyBenefitPotResponse" } }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "myPolicyResponse": { "type": "object", "properties": { "policyReference": { "type": "string", "description": "Public-facing policy reference." }, "name": { "type": "string", "description": "Display name of the policy." }, "status": { "type": "string" }, "policyRoleTypes": { "type": "array", "items": { "type": "string" }, "description": "The active role(s) the caller holds on this policy. A caller may\nhold more than one role on the same policy - for example both\n**Policy Holder** and **Payer**." } } }, "mySchemeOrganisationResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "External identifier of the related record." }, "name": { "type": "string", "description": "Display name of the related record." } }, "description": "The employer organisation the scheme belongs to." }, "mySchemeResponse": { "type": "object", "properties": { "schemeReference": { "type": "string" }, "name": { "type": "string" }, "organisation": { "$ref": "#/components/schemas/mySchemeOrganisationResponse" }, "effectiveFrom": { "type": "string", "description": "Start of the access grant's validity." }, "effectiveTo": { "type": "string", "description": "End of the access grant's validity. Null when open-ended." } } }, "organisationEventResponse": { "type": "object", "properties": { "externalId": { "type": "string" }, "name": { "type": "string" }, "eventType": { "type": "string" }, "description": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date-time", "nullable": true }, "visibleOnPortals": { "type": "boolean", "description": "Whether this event should be surfaced on customer/portal views." }, "personExternalId": { "type": "string" }, "organisationExternalId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "modifiedAt": { "type": "string", "format": "date-time" } } }, "pagedResponseEnvelope_getFeCustomerPolicyResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/getFeCustomerPolicyResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_getPolicyClaimResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/getPolicyClaimResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_myPolicyResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/myPolicyResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_mySchemeResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/mySchemeResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_organisationEventResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/organisationEventResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_portalRoleResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/portalRoleResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_schemeCollectionPolicyResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemeCollectionPolicyResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_schemeCollectionResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemeCollectionResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_schemeCollectionScheduleResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemeCollectionScheduleResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_schemeInvoiceResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemeInvoiceResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "pagedResponseEnvelope_schemeMemberResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/schemeMemberResponse" } }, "pagination": { "$ref": "#/components/schemas/paginationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "paginationResponse": { "type": "object", "properties": { "nextPage": { "type": "string" }, "pageSize": { "type": "integer", "format": "int32" }, "totalItems": { "type": "integer", "format": "int32" } } }, "policyBenefitPotBenefitResponse": { "type": "object", "properties": { "benefitReference": { "type": "string", "description": "External reference of the product version benefit (`PVB-...`).\nThis is the same value a claim line item carries as\n`benefitReference`, so a line item can be matched to its pot." }, "name": { "type": "string", "description": "Display name of the underlying benefit." } } }, "policyBenefitPotCoveredEntityResponse": { "type": "object", "properties": { "coveredEntityReference": { "type": "string", "description": "External reference of the covered entity (`CVE...`), as returned\nby `GET /v1/policies/{policyReference}/covered-entities`." }, "name": { "type": "string", "description": "Display name of the covered entity." } }, "description": "The covered entity the pot belongs to. Present only when\n`potScope` is `Individual`; omitted for pooled (`Dependants`, `Family`) pots." }, "policyBenefitPotResponse": { "type": "object", "properties": { "benefit": { "$ref": "#/components/schemas/policyBenefitPotBenefitResponse" }, "potScope": { "type": "string", "description": "Who the pot is for. `Individual` - one covered entity's own pot.\n`Dependants` - a pooled pot shared by all dependants on the policy.\n`Family` - a pooled pot shared by the whole household." }, "coveredEntity": { "$ref": "#/components/schemas/policyBenefitPotCoveredEntityResponse" }, "periodStart": { "type": "string", "description": "First day of the benefit period (inclusive)." }, "periodEnd": { "type": "string", "description": "Last day of the benefit period (inclusive)." }, "periodStatus": { "type": "string", "description": "Lifecycle status of the benefit period the pot covers. `Active` is\nthe current period. `Expired` periods have ended. `Carried Over`\nperiods have ended and their balance was carried into the next\nperiod's pot." }, "currency": { "type": "string", "description": "ISO 4217 currency code for every amount on this pot." }, "initialAllocation": { "type": "number", "description": "Allowance allocated to the pot at the start of the benefit period.", "format": "double" }, "carryOverAmount": { "type": "number", "description": "Balance carried over from the previous period, where the product\npermits it. `0.00` when none.", "format": "double" }, "adjustmentAmount": { "type": "number", "description": "Manual adjustment applied to the pot. Positive increases the\nallowance, negative reduces it. `0.00` when none.", "format": "double" }, "claimedAmount": { "type": "number", "description": "Total accepted claim value settled against the pot in the period.\n`0.00` when nothing has been claimed.", "format": "double" }, "clawbackAmount": { "type": "number", "description": "Amount clawed back from the pot, for example a reversed claim\npayment. `0.00` when none.", "format": "double" }, "remainingBalance": { "type": "number", "description": "Balance still available to claim. May be negative where an\nadjustment or clawback exceeds the allocation.", "format": "double" }, "sharedPoolPerPersonCap": { "type": "number", "description": "For pooled pots (`Dependants`, `Family`), the maximum any one\nperson may draw from the shared pool in the period. Null when no\nper-person cap applies.", "format": "double" }, "lastUpdatedOn": { "type": "string", "description": "Timestamp the pot was last updated - the point in time the\nbalances are correct as of." } } }, "portalRoleOrganisationResponse": { "type": "object", "properties": { "organisationId": { "type": "string", "description": "Record identifier for the Organisation." }, "externalId": { "type": "string", "description": "External identifier for the Organisation, in the format `ORG` followed\nby eight or more digits. May be omitted where the Organisation has not\nyet been assigned a public reference." }, "name": { "type": "string", "description": "Registered or trading name of the Organisation." } }, "description": "The organisation the role is scoped to, when the role is a corporate\n(Company) context. Omitted entirely for personal (Customer) contexts." }, "portalRolePersonResponse": { "type": "object", "properties": { "contactId": { "type": "string", "description": "Record identifier for the Person." }, "externalId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "fullName": { "type": "string", "description": "Concatenated full name. Provided for convenience; consumers requiring\nstrict structure should prefer `firstName` and `lastName`." }, "email": { "type": "string", "description": "Primary email address held on the Person record." } } }, "portalRoleResponse": { "type": "object", "properties": { "portalUserId": { "type": "string", "description": "Record identifier for the PortalUser." }, "externalId": { "type": "string", "description": "External identifier for the PortalUser, in the format `POR` followed\nby eight or more digits." }, "name": { "type": "string", "description": "Display name of the PortalUser record." }, "email": { "type": "string", "description": "Contact email associated with the PortalUser record." }, "entraObjectId": { "type": "string", "description": "The Entra object identifier (`oid`) the PortalUser is linked to.\nAll entries in a single response share the same value." }, "role": { "type": "string", "description": "The role associated with this PortalUser assignment." }, "tenantType": { "type": "string", "description": "The tenant context in which this role applies. `customer` denotes a\npersonal portal context; `company` denotes a corporate portal context\nscoped to an organisation." }, "isActive": { "type": "boolean", "description": "Indicates whether the PortalUser assignment is currently active. Only\nactive assignments are returned by this endpoint; the field is\nincluded for completeness and forward-compatibility." }, "lastLogin": { "type": "string", "description": "Timestamp of the most recent successful sign-in associated with this\nPortalUser, ISO 8601 UTC. Omitted when the user has never signed in.", "format": "date-time" }, "person": { "$ref": "#/components/schemas/portalRolePersonResponse" }, "organisation": { "$ref": "#/components/schemas/portalRoleOrganisationResponse" } } }, "problemDetailError": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "problemDetails": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/problemDetailError" } } } }, "productVersionBenefitSummaryResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "External reference of the product version benefit, sent as\n`benefitReference` when creating a claim line item." }, "name": { "type": "string", "description": "Product version benefit name." }, "benefit": { "type": "string", "description": "Underlying benefit name." }, "isCore": { "type": "boolean", "description": "Indicates whether this is a core benefit." }, "status": { "type": "string" }, "coveredEntityType": { "type": "string", "description": "The type of entity the benefit covers." } } }, "quickCreateClaimResponse": { "type": "object", "properties": { "claimReference": { "type": "string" } } }, "responseEnvelope_claim": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/claim" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_claimLineItem": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/claimLineItem" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_createFeLocationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/createFeLocationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_createFeOrganisationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/createFeOrganisationResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_createFePolicyEventResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/createFePolicyEventResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_createFePolicyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/createFePolicyResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_getChoiceListResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/getChoiceListResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_getCoveredEntityResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/getCoveredEntityResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_getFePolicyResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/getFePolicyResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_getFeProductResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/getFeProductResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_listChoiceListsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/listChoiceListsResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_listCoveredEntitiesResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/listCoveredEntitiesResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_listProductVersionBenefitsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/listProductVersionBenefitsResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_quickCreateClaimResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/quickCreateClaimResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_schemeCollectionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/schemeCollectionResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_schemeInvoiceResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/schemeInvoiceResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_schemeMemberResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/schemeMemberResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_updateClaimLineItemResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/updateClaimLineItemResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseEnvelope_updateFeCustomerResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/updateFeCustomerResponse" }, "meta": { "$ref": "#/components/schemas/responseMeta" } } }, "responseMeta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Correlation identifier for the response, equal to the inbound `Correlation-Id` when supplied or server-generated otherwise." }, "timestamp": { "type": "string", "description": "Server-side generation time of the response (ISO 8601 UTC).", "format": "date-time" }, "apiVersion": { "type": "string", "description": "Semantic version of the API producing the response." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/responseWarning" }, "description": "Non-fatal advisories returned alongside a successful response." } } }, "responseWarning": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "schemeCollectionAmountResponse": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "nullable": true }, "currencyCode": { "type": "string" } } }, "schemeCollectionPolicyAmountResponse": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "nullable": true }, "currencyCode": { "type": "string" } } }, "schemeCollectionPolicyResponse": { "type": "object", "properties": { "name": { "type": "string" }, "policyReference": { "type": "string", "description": "Reference of the associated policy." }, "amount": { "$ref": "#/components/schemas/schemeCollectionPolicyAmountResponse" }, "grossAmount": { "$ref": "#/components/schemas/schemeCollectionPolicyAmountResponse" }, "taxAmount": { "$ref": "#/components/schemas/schemeCollectionPolicyAmountResponse" }, "isActive": { "type": "boolean" } } }, "schemeCollectionResponse": { "type": "object", "properties": { "schemeCollectionReference": { "type": "string", "description": "External identifier of the collection, used to address it and to retrieve its per-policy breakdown. Treat as an opaque string; the reference format is not yet finalised." }, "name": { "type": "string" }, "dueDate": { "type": "string" }, "collectedDate": { "type": "string", "description": "When the collection was taken. Null for a forthcoming collection." }, "collectionStatus": { "type": "string" }, "memberCount": { "type": "integer", "format": "int32", "nullable": true }, "totalAmount": { "$ref": "#/components/schemas/schemeCollectionAmountResponse" }, "collectedAmount": { "$ref": "#/components/schemas/schemeCollectionAmountResponse" }, "isActive": { "type": "boolean" } } }, "schemeCollectionSchedulePaymentMethodResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "External identifier of the related record." }, "name": { "type": "string", "description": "Display name of the related record." } } }, "schemeCollectionScheduleResponse": { "type": "object", "properties": { "schemeCollectionScheduleReference": { "type": "string", "description": "External identifier of the collection schedule. Treat as an opaque string; the reference format is not yet finalised." }, "name": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "collectionDay": { "type": "integer", "format": "int32", "nullable": true }, "paymentFrequency": { "type": "string" }, "paymentMethod": { "$ref": "#/components/schemas/schemeCollectionSchedulePaymentMethodResponse" }, "isActive": { "type": "boolean" } } }, "schemeInvoiceAmountResponse": { "type": "object", "properties": { "amount": { "type": "number", "format": "double", "nullable": true }, "currencyCode": { "type": "string" } } }, "schemeInvoiceResponse": { "type": "object", "properties": { "invoiceReference": { "type": "string", "description": "External identifier of the invoice, used to address it and to retrieve its per-policy breakdown. Treat as an opaque string; the reference format is not yet finalised." }, "invoiceNumber": { "type": "string", "description": "The finance-facing invoice number shown to the administrator. Not used to address the invoice." }, "invoiceDate": { "type": "string" }, "dueDate": { "type": "string" }, "paidDate": { "type": "string" }, "invoiceStatus": { "type": "string" }, "grossAmount": { "$ref": "#/components/schemas/schemeInvoiceAmountResponse" }, "netAmount": { "$ref": "#/components/schemas/schemeInvoiceAmountResponse" }, "taxAmount": { "$ref": "#/components/schemas/schemeInvoiceAmountResponse" }, "paidAmount": { "$ref": "#/components/schemas/schemeInvoiceAmountResponse" } } }, "schemeMemberLevelResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "External identifier of the related record." }, "name": { "type": "string", "description": "Display name of the related record." } }, "description": "The product version level for this member." }, "schemeMemberResponse": { "type": "object", "properties": { "schemeMemberReference": { "type": "string", "description": "Unique, external-facing identifier of the scheme member. Stable for the life of the record; use it to address the member (for example, on removal)." }, "employeeNumber": { "type": "string", "description": "Employer-assigned member reference. Not unique within a scheme (employers may reuse values), so it must not be used to address a member." }, "personExternalId": { "type": "string", "description": "External identifier of the matched or created Person record." }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "memberType": { "type": "string" }, "memberStatus": { "type": "string" }, "isActive": { "type": "boolean" }, "enrolmentDate": { "type": "string" }, "terminationDate": { "type": "string" }, "level": { "$ref": "#/components/schemas/schemeMemberLevelResponse" }, "policyReference": { "type": "string", "description": "The policy reference for this member, when provisioned." }, "createdAt": { "type": "string" }, "modifiedAt": { "type": "string" } } }, "updateClaimLineItemRequest": { "type": "object", "properties": { "name": { "type": "string" }, "claimDate": { "type": "string" }, "benefitDate": { "type": "string" }, "totalCost": { "type": "number", "format": "double", "nullable": true }, "totalAmountCovered": { "type": "number", "format": "double", "nullable": true }, "excessApplied": { "type": "number", "format": "double", "nullable": true }, "copayApplied": { "type": "number", "format": "double", "nullable": true }, "invoiceReference": { "type": "string" }, "benefitReference": { "type": "string" }, "claimantReference": { "type": "string" } } }, "updateClaimLineItemResponse": { "type": "object", "properties": { "claimLineItemReference": { "type": "string" }, "name": { "type": "string" }, "lineStatus": { "type": "string" }, "claimDate": { "type": "string" }, "benefitDate": { "type": "string", "description": "Date the benefit is claimed for (`YYYY-MM-DD`). Depending on the benefit this is the treatment date, the discharge date, or the\nbirth / adoption date. `benefitDate` replaces the earlier\n\"treatment date\" (`treatmentDate`) concept. Null on line items\ncreated before this field was captured." }, "totalCost": { "type": "number", "format": "double", "nullable": true }, "totalAmountCovered": { "type": "number", "format": "double", "nullable": true }, "excessApplied": { "type": "number", "format": "double", "nullable": true }, "copayApplied": { "type": "number", "format": "double", "nullable": true }, "invoiceReference": { "type": "string" }, "externalId": { "type": "string" }, "benefit": { "$ref": "#/components/schemas/updateClaimLineItemResponseBenefit" }, "claimant": { "$ref": "#/components/schemas/updateClaimLineItemResponseClaimant" } } }, "updateClaimLineItemResponseBenefit": { "type": "object", "properties": { "benefitReference": { "type": "string" }, "name": { "type": "string" } } }, "updateClaimLineItemResponseClaimant": { "type": "object", "properties": { "coveredEntityReference": { "type": "string", "description": "Reference of the covered entity (claimant)." }, "name": { "type": "string", "description": "Name of the covered entity (claimant)." } } }, "updateFeCustomerAddressRequest": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" } } }, "updateFeCustomerAddressResponse": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "postcode": { "type": "string", "description": "UK postcode. Validated against a UK postcode pattern on write." }, "country": { "type": "string" } } }, "updateFeCustomerRequest": { "type": "object", "properties": { "title": { "type": "string" }, "firstName": { "type": "string" }, "middleName": { "type": "string" }, "lastName": { "type": "string" }, "dateOfBirth": { "type": "string" }, "email": { "type": "string" }, "address": { "$ref": "#/components/schemas/updateFeCustomerAddressRequest" } } }, "updateFeCustomerResponse": { "type": "object", "properties": { "externalId": { "type": "string" }, "email": { "type": "string", "description": "Primary email address. Read-only through this endpoint; email changes are\nmanaged via the Entra External ID account recovery flow." }, "title": { "type": "string", "description": "Honorific or salutation (for example, `Mr`, `Ms`, `Dr`)." }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dateOfBirth": { "type": "string", "description": "Date of birth in `YYYY-MM-DD` format. Must not be in the future." }, "address": { "$ref": "#/components/schemas/updateFeCustomerAddressResponse" } } }, "updateFeOrganisationAddressRequest": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "city": { "type": "string" }, "county": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } } }, "updateFeOrganisationRequest": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "$ref": "#/components/schemas/updateFeOrganisationAddressRequest" } } } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://shcintegrationnp.ciamlogin.com/1a65d85e-74c5-461b-a156-d253499c6d93/oauth2/v2.0/authorize", "tokenUrl": "https://shcintegrationnp.ciamlogin.com/1a65d85e-74c5-461b-a156-d253499c6d93/oauth2/v2.0/token", "scopes": { "openid": "OpenID Connect", "offline_access": "Offline access", "api://d8b322f0-9b4d-478b-a4ee-8c54484375a9/api.read": "Read access", "api://d8b322f0-9b4d-478b-a4ee-8c54484375a9/api.write": "Write access" } } } } } }, "security": [ { "OAuth2": [] } ] }