# Co-applicant BRE and Auto-Rejection Support

---


## CRED-6112 — 2026-04-05

### Overview

Enhanced the Business Rule Engine (BRE) and Auto-Rejection system to support **Co-applicants**. Previously, the BRE only evaluated the primary applicant. The system now allows for independent rule evaluations for co-applicants based on their role (e.g., adding income for higher eligibility vs. just being a signing guarantor).
Currently only the rejection part is implemented for the co-applicant

---

### Business Rules

- **Applicant Types**: 
  - `1`: Primary Applicant (Borrower)
  - `2`: Co-applicant (Guarantor)
- **Co-applicant Roles**:
  - **In-come**: Co-applicant's income and bureau are used for eligibility calculation.
  - **Signing**: Co-applicant is only for legal/guaranty purposes; income is not considered, but credit history/behavior rules still apply.
- **Rules Differentiation**:
  - Primary applicants follow standard `auto_reject_rule` and `approval_rule` paths.
  - Co-applicants use specific rule sets defined under `applicant_type = 2`.
- **BRE API Policies**:
  - `policy-rejection-income`: Applied when the co-applicant is being evaluated for income addition.
  - `policy-rejection-signing`: Applied when the co-applicant is only for signing.
  - `policy-rejection`: Standard rejection policy (fallback for backward compatibility).

---

### Logic Added

#### Co-applicant Rejection Evaluation
`AutoRejection::autoRejectCoApplicantJSONBRE($grade, $id, $tracking_id)`
- Fetches rules where `applicant_type = 2` for the given merchant grade.
- Groups failure results by role (`income` vs `signing`) into a structured log format.
- Uses `JSONBREController::runRejection` with its specific `applicant_type`.
- Triggers from generate soft bureau api call `ConsumerApplicationController::generateSoftEquifaxReport`.

#### Unified BRE Runner
`JsonBREController::runRejection($id, $req_id, $auto_reject_rule, $json_bre_for_log, $pirimid_tracking_id, $applicant_type)`
- Dynamically switches between primary and co-applicant policies based on `$applicant_type`.
- Retrieves the correct `CreditReport` and `PirimidBankAnalysis` (Bank Statement analysis) for the specific applicant being evaluated.
- Supports multi-policy payloads (e.g., evaluating both income and signing roles in a single request).

#### Logging & Auditing
- **BRE Logs**: `bre_logs.applicant_type` column stores which applicant was being processed.
- **Auto-Rejection Logs**: `auto_reject_logs.applicant_type` stores the rejection reason specifically for the co-applicant if applicable.
- **Webhooks**: Webhook payloads now include the `applicant_type` to inform merchants which party triggered the rejection.

---

### Impact — Files Changed / Added

| File | Type | Change |
|------|------|--------|
| `app/Http/Controllers/JsonBREController.php` | Modified | Updated `runRejection` and `store_jsonbre_response` to handle `applicant_type` and roles |
| `app/Http/Controllers/Grade/AutoRejection.php` | Modified | Added `autoRejectCoApplicantJSONBRE()`; updated `autoRejectLog()` to support co-applicant rejection logging |
| `database/migrations/2026_04_03_231256_add_applicant_type_to_auto_reject_rule_table.php` | Added | Migration to add `applicant_type` to `auto_reject_rule` table |
| `database/migrations/2026_04_05_161849_add_applicant_type_to_bre_logs.php` | Added | Migration to add `applicant_type` to `bre_logs` table |

---

#### Manual Verification
1. Create an application with a co-applicant.
2. Trigger the auto-rejection logic for the co-applicant.
3. Verify that `bre_logs` and `auto_reject_logs` correctly identify the co-applicant as the source.
4. Check the edit page to ensure the rejection reason specifies the co-applicant role.




## CRED-6234 — 2026-05-27

### Overview
Fixed inconsistencies in the co-applicant BRE rejection flow. Previously, a co-applicant rejection was incorrectly triggering a "rejected" WhatsApp notification for the entire application, and the `Pirimid` bank analysis webhook was incorrectly rejecting the application entirely.

### Logic Modified
- **`Pirimid.php`**: Added a check to ensure the application state is only updated to "rejected" if the primary applicant (`applicant_type == 1`) fails the BRE. Co-applicant failures now safely skip the application state update and halt the auto-decision flow.
- **`AutoRejection.php`**: Gated the WhatsApp group status notification (`sendGroupStatusNotification`) inside `autoRejectLog()` behind an `applicant_type == 1` check to prevent false "rejected" notifications when only a co-applicant fails. Webhooks remain unaffected.

### Impact — Files Changed / Added

| File | Type | Change |
|------|------|--------|
| `app/Pirimid.php` | Modified | Added `applicant_type == 1` check before rejecting the application |
| `app/Http/Controllers/Grade/AutoRejection.php` | Modified | Prevented `sendGroupStatusNotification` for co-applicants (`applicant_type == 2`) |

---