# Beneficiary Verification PI Update

## Purpose

This document describes the backend response change for beneficiary verification and the frontend updates required to support dependent-specific referral numbers.

The main change is that dependents now have their own unique `referral_number` values instead of sharing the principal's number.

## Why This Changed

Previously, the principal and dependent could effectively resolve under the same reference number.

That caused a hospital user to enter a dependent's reference and receive the principal's identity instead.

The backend now enforces this pattern:

- Principal: `REF20265E43AA`
- Dependent: `REF20265E43AA-01`

The dependent still remains linked to the principal through the relationship fields.

## Endpoint

- Method: `POST`
- URL: `/api/admin/patient/verify-beneficiary`
- Auth: `auth:sanctum`

## Request Body

```json
{
  "billing_category_id": 10,
  "linked_entity_id": 22,
  "linked_entity_type": "Employer",
  "referral_number": "REF20265E43AA-01"
}
```

## Response Envelope

```json
{
  "status": true,
  "response": {},
  "message": "Beneficiary verified successfully"
}
```

The frontend should read the actual payload from `response`.

## Updated Success Response

```json
{
  "status": true,
  "response": {
    "verified": true,
    "beneficiary": {
      "id": 17,
      "referral_number": "REF20265E43AA-01",
      "staff_number": null,
      "full_name": "Godwin Johnson",
      "first_name": "Godwin",
      "middle_name": null,
      "last_name": "Johnson",
      "phone": "08030000000",
      "email": "godwin@example.com",
      "address": "Benin City",
      "gender": "male",
      "date_of_birth": "2015-02-10",
      "type": "dependent",
      "relationship": "Child",
      "parent_name": "Peter Johnson",
      "parent_referral_number": "REF20265E43AA",
      "is_active": true
    },
    "already_registered": false,
    "patient": null
  },
  "message": "Beneficiary verified successfully"
}
```

## New Field Added

### `beneficiary.parent_referral_number`

- Type: `string | null`
- Meaning: the principal beneficiary's referral number
- Present for dependents when a parent exists
- Usually `null` for staff beneficiaries

This field is additive. Existing fields remain unchanged.

## Frontend Impact

### 1. Stop assuming dependent and principal share the same reference

The frontend should treat `beneficiary.referral_number` as the identity key entered by the hospital user.

Do not replace it with the principal's referral number.

### 2. Show dependent relationship context

When `beneficiary.type === 'dependent'`, the UI should display:

- Dependent referral number from `beneficiary.referral_number`
- Relationship from `beneficiary.relationship`
- Principal name from `beneficiary.parent_name`
- Principal reference from `beneficiary.parent_referral_number`

### 3. Use the dependent's own referral number for onboarding

If the user continues into patient registration or beneficiary-linked onboarding, continue passing or displaying the dependent's own `referral_number`.

### 4. Preserve current staff flow

For principal or staff beneficiaries, the existing flow does not need structural changes. The new `parent_referral_number` field can simply be ignored when `null`.

## Suggested UI Copy

### For dependent verification result

- `Beneficiary verified`
- `Dependent: Godwin Johnson`
- `Reference: REF20265E43AA-01`
- `Relationship: Child`
- `Principal: Peter Johnson`
- `Principal Reference: REF20265E43AA`

## Suggested Frontend Types

```ts
export interface VerifiedBeneficiary {
  id: number;
  referral_number: string;
  staff_number: string | null;
  full_name: string;
  first_name: string;
  middle_name: string | null;
  last_name: string;
  phone: string | null;
  email: string | null;
  address: string | null;
  gender: 'male' | 'female' | 'other' | null;
  date_of_birth: string | null;
  type: 'staff' | 'dependent';
  relationship: string | null;
  parent_name: string | null;
  parent_referral_number: string | null;
  is_active: boolean;
}

export interface VerifyBeneficiaryResponse {
  verified: boolean;
  beneficiary: VerifiedBeneficiary;
  already_registered: boolean;
  patient: {
    id: number;
    file_number: string;
    full_name: string;
  } | null;
}
```

## Suggested Rendering Logic

```ts
const isDependent = response.beneficiary.type === 'dependent';

const displayReference = response.beneficiary.referral_number;
const displayPrincipalReference = response.beneficiary.parent_referral_number;
```

Recommended conditional UI:

- Always show `beneficiary.referral_number`
- Show `relationship`, `parent_name`, and `parent_referral_number` only for dependents

## Error Handling

If the referral number does not match an active beneficiary under the selected linked entity, the backend returns:

```json
{
  "status": false,
  "response": null,
  "message": "Beneficiary not found or inactive"
}
```

The frontend should not try to fall back to a principal lookup based on a partial reference.

## QA Checklist

- Principal beneficiary can still be verified with their own reference number.
- Dependent beneficiary can be verified with their own suffixed reference number.
- A dependent lookup returns the dependent's personal details, not the principal's.
- Dependent lookup response includes `relationship`, `parent_name`, and `parent_referral_number`.
- Registration or onboarding continues with the dependent's own `referral_number`.
- Existing staff verification flow still works without special-case regressions.