# Secure Call Verification — Verify Bank-Initiated Calls

**Purpose**  
Let the app confirm whether an incoming/recent call was genuinely initiated by the bank—helping stop voice phishing and number spoofing.

**System architecture**

1. **Bank Call Center** reports each outbound call to the Secure Call backend.
2. **Secure Call Backend** records the call data.
3. Mobile App + SDK queries the backend and displays verification status.

**Server-to-server API (ReportCall)**  
**Endpoint:** `POST /api/v1/ReportCall`  
**Fields:** `phone_number` (req), `uid` (req), `call_reason` (opt), `call_team` (opt), `call_agent` (opt)

**Example (curl)**

```bash
curl -X POST "https://securecall.example.com/api/v1/ReportCall" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "uid": "123456789",
    "call_reason": "Verify Transaction",
    "call_team": "Fraud Department",
    "call_agent": "John Smith"
  }'

```

**Android SDK integration**  
**Permission (AndroidManifest.xml):**

```
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

```

If missing, `CheckCallStatus()` returns `UNKNOWN`.

**SDK method**

```kotlin
val result = collectorAgent.CheckCallStatus()

```

**Statuses**

- `CALL_APPROVED` — Legitimate bank-initiated call (active or recent)
- `UNAPPROVED_RECENT_CALL` — Recent call detected but not reported → potential fraud
- `NO_RECENT_CALL` — No active/recent call
- **UNKNOWN** — Insufficient info (incompatibility or missing permission)

**Sample returns**  
Legitimate:

```bash
{
  "STATUS": "CALL_APPROVED",
  "CALL_REASON": "Verify Transaction",
  "CALL_TEAM": "Fraud Department",
  "CALL_AGENT": "John Smith"
}

```

**Unapproved:**

```bash
{ "STATUS": "UNAPPROVED_RECENT_CALL" }

```

**No call:**

```bash
{ "STATUS": "NO_RECENT_CALL" }

```

**UI recommendations**

- `CALL_APPROVED` → Green banner: “This call is verified.” (show agent + reason)
- `UNAPPROVED_RECENT_CALL` → Yellow warning: “Be cautious—possible fraud.”
- **UNKNOWN** → Gray info: “Unable to verify call status.”

**End-to-end example**

1. Agent calls customer and backend sends `ReportCall`.
2. Customer opens the app during the call.
3. App invokes `CheckCallStatus()` and receives `CALL_APPROVED`.
4. App shows green banner with agent/team/reason.