MRN Module

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 auto-created during insurance policy creation — one per covered dependant at the benefit’s provider. See the Insurance Policy module for details.

Create Flow

Auth Guards by Endpoint

Endpoint	App (JWT) user	Benefit provider	Admin / platform	Notes
`POST /mrns`	✓	✓	✓	App user: dependant must belong to the token user. No route-level gate — scoping is enforced in core
`GET /mrns`	✓ own only	✓ own provider	✓	App user is force-scoped to their own `primary_user_id`; a benefit provider is force-scoped to its own `benefit_provider_id`
`GET /mrns/{id}`	✓ own only	✓ own provider	✓	Ownership / provider-scope mismatch returns 404 (existence not leaked); also 404 if inactive
`PATCH /mrns/{id}`	—	✓ own provider	✓	Coarse gate (`require_benefit_provider`) then core strict-checks the MRN’s `benefit_provider_id`. Replaces `external_mrn` only
`DELETE /mrns/{id}`	—	✓	✓	Trusted-backend only (admin / platform / benefit provider). Sets `status → INACTIVE`

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, or mrn.

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

curl -X POST http://localhost:8080/mrns \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{
    "dependant_id": "01926b3a-7c2e-7d4f-a1b2-c3d4e5f60001",
    "benefit_provider_id": "018f4c2a-1b3e-7d8f-9a0b-2c3d4e5f6a7b",
    "external_mrn": {
      "temp_number": "TMP-98765",
      "mrn": "MRN-12345"
    }
  }'

curl -X POST http://localhost:8080/mrns \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{
    "dependant_id": "01926b3a-7c2e-7d4f-a1b2-c3d4e5f60001",
    "benefit_provider_id": "018f4c2a-1b3e-7d8f-9a0b-2c3d4e5f6a7b"
  }'

{
  "id": "01926b3a-7c2e-7d4f-a1b2-c3d4e5f60020",
  "primary_user_id": "047382910564",
  "dependant_id": "01926b3a-7c2e-7d4f-a1b2-c3d4e5f60001",
  "benefit_provider_id": "018f4c2a-1b3e-7d8f-9a0b-2c3d4e5f6a7b",
  "external_mrn": {
    "temp_number": "TMP-98765",
    "mrn": "MRN-12345"
  },
  "status": "ACTIVE",
  "created_at": "2026-04-12T10:00:00Z",
  "last_modified_at": "2026-04-12T10:00:00Z"
}

`external_mrn` Object

Field	Type	Required	Description
`temp_number`	string	no	Temporary registration number assigned by the provider
`mrn`	string	no	Final medical record number assigned by the provider

Both fields are optional. The external_mrn field itself is also optional on create — an MRN record can exist without external identifiers (e.g., when auto-created during policy purchase).

Error Codes

Code	HTTP	Description
`MR_1100`	500	Internal server error
`MR_1101`	404	MRN not found or inactive
`MR_1102`	403	JWT user accessing an MRN belonging to another user’s dependant
`MR_1103`	409	MRN already exists for this dependant + provider combination
`MR_1104`	404	Dependant not found or inactive
`MR_1105`	404	Benefit provider not found or inactive
`MR_1106`	400	Invalid UUID in filter or request body

Overview

Architecture

Decisions

Modules

Overview

Create Flow

Auth Guards by Endpoint

Endpoints

POST /mrns

GET /mrns

GET /mrns/{id}

PATCH /mrns/{id}

DELETE /mrns/{id}

Request / Response Examples

`external_mrn` Object

Error Codes

​Overview

​Create Flow

​Auth Guards by Endpoint

​Endpoints

POST /mrns

GET /mrns

GET /mrns/{id}

PATCH /mrns/{id}

DELETE /mrns/{id}

​Request / Response Examples

​external_mrn Object

​Error Codes

Overview

Create Flow

Auth Guards by Endpoint

Endpoints

Request / Response Examples

`external_mrn` Object

Error Codes