Enterprise FE API (1.0)

Health check.

Applies a partial update to the customer record identified by the supplied external identifier, using JSON Merge Patch semantics (RFC 7396).

Only the fields present in the request body are updated. Omitted fields are left unchanged. Fields outside the documented allowlist are rejected with a validation error; attempts to modify system or unmanaged fields (for example, externalId, email, or state flags) are not permitted.

Fields fall into two tiers. Immediately applicable fields (title, address) are written straight away and the updated record is returned with 200. Verification-gated fields (firstName, middleName, lastName, dateOfBirth) are not applied directly: submitting any of them creates a change request that is verified by an external service — which may approve or reject it — and the response is 202 Accepted with the change request. Some verifications also require supporting documents (for example a marriage certificate for a surname change); the change request indicates whether evidence is required and which document types. Where a single request mixes both tiers, the immediately applicable fields are written and a change request is created for the rest.

Authorisation follows the same role-scoped model as the GET endpoint. A Customer may update only their own record; broader roles may update records within their scope.

All successful updates are captured in the audit trail with before-and-after values. The API application log records only request metadata — which fields were updated, when, and by whom — not the values themselves, in line with UK GDPR data minimisation.

Inactive customer records cannot be updated; attempts return 410 Gone.

Returns a curated payload of personal details for the customer identified by the supplied external identifier. The response is a shaped data transfer object — internal system fields are not exposed.

Authorisation is role-scoped. A caller with the Customer role may retrieve only their own record. Callers with broader roles (SchemeAdministrator, ClaimsAssessor) may retrieve records within their scope. Requests outside the caller's scope return 403 Forbidden.

Inactive customer records return 410 Gone with a body indicating the record exists but is no longer active.

Returns a list of policies for a given customer identified by their reference. The customer is the policy holder.

The response is a paged collection per the Sovereign Health Care API Design Standards: the data array carries the policy summaries, the pagination block carries navigation state, and meta carries correlation metadata. A customer with no qualifying policies receives 200 OK with data: [] — an empty collection is not an error.

Register a new organisation in the downstream Core system.

Applies a partial update to the organisation identified by the supplied external identifier.

Only the fields present in the request body are updated; omitted fields are left unchanged. Fields outside the documented set are rejected with a validation error, as are the platform-generated externalId, createdAt and modifiedAt.

Two deliberate divergences from RFC 7396 JSON Merge Patch, both platform conventions rather than quirks of this operation:

1. An explicit null is a no-op, not a removal. Sending {"email": null} leaves the stored email untouched rather than clearing it. There is currently no way to clear an optional field through this endpoint.

2. director cannot be changed here; it is accepted on create only.

A body that changes nothing is rejected with 400 rather than silently succeeding. An address may be partial: supplying address with only city set changes the city and leaves the rest of the stored address intact.

If-Match is accepted with the value *, which requires the organisation to exist. A concrete ETag is not supported - no endpoint on this platform issues an ETag, so no caller can hold a valid one, and any other value is rejected with 409 rather than silently ignored.

The response is 200 with an empty body: the stored record is not read back. Re-read with GET if the current record is needed.

Register a new location for an organisation in the downstream Core system.

Returns the choices (code + label pairs) for the named choice list. Internal numeric identifiers and platform-specific field names are implementation details and are intentionally omitted from the response.

Returns a lightweight manifest of every choice list available in the catalogue. Clients call GET /v1/reference-data/{listName} to retrieve the choices themselves.

Returns a fully expanded product payload — provider, provider settings, all versions, and for each version the benefits, benefit coverages, levels, level benefits and level pricing.

Returns the benefits configured on a product version - the selectable benefits for a claim line item. Used to populate the benefit picker when adding a claim line item: the caller selects a benefit and its reference is sent as the line item's benefitReference.

productVersionReference is the product version's external reference, obtained from the policy's product version.

Returns a fully expanded policy payload - policy details, the resolved product / version / cover level references, pricing, policy holder (person, contact, consents), payer and Direct Debit details, additional adults, dependants, referral data, and recorded audit events.

The response mirrors the structure of the create-policy request body and adds system-generated identifiers (policyId, policyReference, contactId, contactExternalId), the policy status, and audit metadata.

The response also carries the provider that underwrites the policy (identifier, reference and name), and a coveredEntityReference (CVE...) on the policy holder, on each additional adult and on each dependant. Use a coveredEntityReference with GET /v1/policies/{policyReference}/covered-entities/{coveredEntityReference} to read the details of that covered entity.

Access is subject to object-level authorization (see Authentication and authorization in the API description): the caller must hold an active role on the requested policy. A caller with no active role receives 404, indistinguishable from an unknown reference.

Creates a new policy at Draft status and the supporting customer, policy holder role, covered entity, and audit event records in a single atomic transaction.

Business rules executed during the call:

• Existing customer match - the platform searches for an existing customer using surname + date of birth + email address. A match reuses the existing record; no match creates a new one.
• Banned customer rejection - if the matched customer's bannedCustomer flag is true, the application is rejected with HTTP 400 / CUSTOMER_BANNED.
• Similar policy detection - if the matched customer already holds a policy on the same product and product version, the create proceeds and a non-blocking SIMILAR_POLICY_EXISTS warning is returned in meta.warnings.

Atomicity guarantee: if any inner write fails, all writes for the application are rolled back so the caller can cleanly retry.

Appends a new audit / lifecycle event to an existing policy, identified by its public reference. Events provide an immutable, append-only history of what happened to a policy and when - policy creation, cover-level changes, premium changes, cancellations, renewals, and so on - supporting servicing visibility, audit, and FCA record-keeping.

The event is written as a single record linked to the parent policy. Optional before / after detail (status, funding type, member type, cover level, premium) may be supplied through the change object for transition-type events (for example COVER_LEVEL_CHANGE or PREMIUM_CHANGE).

This operation is append-only: it creates a new event and never mutates the policy header or any existing event. The authenticated principal is recorded against the event as the performer.

Responses follow the Sovereign Health Care API Design Standards: a successful create returns the created event inside a data + meta envelope; errors use RFC 9457 application/problem+json.

Returns the policies on which the authenticated caller currently holds an active policy role.

The caller is resolved from the bearer token's identity to the linked person, and the response lists the policies on which that person holds an active role - a current, active role whose effective period includes today's date.

Each policy appears once; where the caller holds more than one role on the same policy (for example both Policy Holder and Payer), all such roles are listed in policyRoleTypes. The policies are returned in the standard collection envelope data array; callers with no active policy roles receive an empty data array.

Returns the entities covered by the policy - the people (and, for some products, animals) that claims can be made for. Used to populate the claimant picker when adding a claim line item: the caller selects a covered entity and its coveredEntityReference (CVE...) is sent as the line item's claimantReference.

Only active covered entities are returned.

Access is subject to object-level authorization: the caller must hold an active role on the policy. A caller with no active role receives 404, indistinguishable from an unknown reference.

Returns the details of one covered entity on the policy, identified by its external reference (CVE...). Used to drill into a covered entity from the policy view, and by processes such as claims evaluation that need the cover details of a claimant.

The covered entity is a policy administration (PAS) record. The response holds the PAS detail - entity type, member type, status, effective dates and the active exclusions - together with references to the related Core records:

• person.personReference (PER...) - the covered person. Use it with GET /v1/customers/{externalId} in the Customer API.
• organisations[].organisationReference (ORG...) - the organisations associated with the covered entity. In this version that is the employer of the scheme the policy belongs to. Use it with GET /v1/organisations/{externalId} in the Organisation API.

Person and organisation detail (names, contact details, addresses) is deliberately not returned here: it is Core data and is read from the Core APIs with the references above.

Active and inactive covered entities are both returned; status says which. Only active exclusions are returned.

Access is subject to object-level authorization: the caller must hold an active role on the policy. The API responds 404 when the policy is unknown, when the caller holds no active role on it, and when the covered entity is unknown or belongs to a different policy. The three cases are indistinguishable.

Returns the benefit pots on the policy. A benefit pot is the allowance for one benefit over one benefit period: the amount allocated at the start of the period (initialAllocation), the amount claimed against it to date (claimedAmount), and what is left (remainingBalance), together with the period start and end dates.

Pots are held at benefit level. A benefit may have more than one pot on the same policy: an Individual pot for each covered entity, or a pooled Dependants / Family pot shared across the household. potScope says which, and coveredEntity is present only on Individual pots.

By default only pots for the current benefit period are returned (periodStatus = Active). Pass includeHistoricPeriods=true to also return Expired and Carried Over periods.

Pass coveredEntityReference to return only the pots that apply to one covered entity - for example to show one person's remaining cover. The result holds that covered entity's Individual pots plus the pooled pots the covered entity shares: every Family pot, and the Dependants pots when the covered entity's member type is Dependant. Individual pots of other covered entities are left out. The covered entity must be on this policy; an unknown reference, or one that belongs to a different policy, gives 400.

Items are ordered by periodStart descending (current period first), then benefit.name ascending, then potScope (Individual, Dependants, Family), then coveredEntity.coveredEntityReference.

Access is subject to object-level authorization: the caller must hold an active role on the policy. A caller with no active role receives 404, indistinguishable from an unknown reference.

Returns the list of active portal role assignments held by the customer. The API derives the Entra object identifier (oid) from the bearer token and resolves the matching PortalUser records, filtering to those marked active.

A single Entra identity may hold multiple portal role assignments (for example, a Customer who is also a SchemeAdministrator on a corporate scheme). Each assignment is returned as a discrete PortalRole entry.

An authenticated caller with no active portal role assignments receives a 200 OK response with data: []. This is not an error condition — it indicates a recognised identity that has not yet been onboarded to any portal role.

This endpoint is the canonical mechanism for portals and broker integrations to discover the caller's available contexts after sign-in. It does not require a path parameter; identity is taken from the bearer token alone.

Returns the schemes the authenticated caller has access to. Access is granted via the caller's portal-role scheme assignments. The caller's Entra object identifier (oid) is resolved from the bearer token; no path parameter is required. An authenticated caller with no scheme grants receives 200 with an empty list.

Returns a single collection belonging to the scheme, addressed by its collection reference. Provides the header detail (due date, status, member count and totals) for the collection drill-down.

Returns the per-policy breakdown of a single scheme collection: the policies the collection is (or will be) applied to, and the amount attributed to each. The collection must belong to the scheme in the path; otherwise 404 is returned so a caller cannot read another scheme's breakdown.

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.