Auth guards vary by endpoint — Create, List, and Get accept app (JWT) users plus trusted-backend callers (admin, platform, benefit provider). Update and Delete are restricted to trusted-backend callers (admin or benefit provider — not app users). JWT ownership and provider-scope checks happen in core, not at the route level.

Overview

An MRN (Medical Record Number) links a dependant to a benefit provider with an external identifier. Each MRN is uniquely scoped to one (dependant_id, benefit_provider_id) pair — only one active MRN per dependant per provider is allowed. The external identifier is stored as a JSONB object (external_mrn) with two optional fields: temp_number (a temporary registration number) and mrn (the final medical record number). Both may be null initially and populated as the provider assigns them. Routes are flat at /mrns (no user nesting). The primary_user_id is derived server-side from the dependant row — callers never supply it.
MRN records are also created by the server: when an insurance policy, health checkup or consultation is created and Superposition lists CREATE_MRN for that benefit. See ADR-011.

Create Flow


Auth Guards by Endpoint


Endpoints

POST /mrns

Create an MRN linking a dependant to a benefit provider.

GET /mrns

List MRNs. Filter by dependant_id, benefit_provider_id, primary_user_id, statuses, mrn (exact match on the MRN or temp number), or a created_at window.

GET /mrns/{id}

Fetch a single active MRN by its internal UUID.

PATCH /mrns/{id}

Replace the external_mrn JSONB. Admin or the owning benefit provider. Used to backfill mrn once the provider issues it.

DELETE /mrns/{id}

Soft-delete (status → INACTIVE). Trusted-backend caller (admin / platform / benefit provider).

Request / Response Examples

external_mrn Object

Both fields are optional. The external_mrn field itself is also optional on create — an MRN record can exist without external identifiers (e.g., created by an admin before the provider assigns one).

Error Codes