Get Driver Referral Network

# Get Driver Referral Network (`/driver/referrals`) Retrieves the authenticated driver's personal referral code, the total count of referees, and the detailed list of users and drivers who registered using their referral code. --- ### Endpoint Overview - **Method:** `GET` - **Route:** `/api/v1/driver/referrals` - **Authentication:** `Bearer Token (Driver JWT)` - **Content-Type:** `N/A` --- ### Request Headers | Header | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `string` | **Yes** | Format: `Bearer` | --- ### Request Body Schema _None (GET request)_ --- ### Response Body Schema (`200 OK`) | Top-Level Key | Data Type | Description | | --- | --- | --- | | `referral_code` | `string` | Driver's own unique referral code (e.g. `"CAP_8X9K2"`) | | `total_referred` | `integer` | Total count of registered referees | | `referred_users` | `array` | List of referees (both drivers and riders) | #### `Referee Item Fields` | Field | Data Type | Nullable | Allowed Values / Constraints | Description | | --- | --- | --- | --- | --- | | `id` | `string` | No | Prefixed with `drv_` or `usr_` | Unique account ID of referee | | `name` | `string` | Yes | String | Full name of referee | | `phone` | `string` | No | E.164 string format | Registered phone number | | `profile_image_url` | `string` | Yes | Valid URL | Avatar image URL | | `type` | `enum` | No | `"DRIVER"`, `"USER"` | Platform role of referee | | `referred_at` | `string` | No | ISO 8601 Timestamp | Registration timestamp | --- ### `Response Examples` #### ``1. `200 OK` — Referrals Found`` ``` json { "referral_code": "CAP_8X9K2", "total_referred": 2, "referred_users": [ { "id": "drv_1a2b3c4d5e", "name": "Suresh Patel", "phone": "+919811122233", "profile_image_url": "https://example.com/profiles/suresh.jpg", "type": "DRIVER", "referred_at": "2026-09-15T10:30:00.000Z" }, { "id": "usr_9z8y7x6w5v", "name": "Priya Sharma", "phone": "+919844455566", "profile_image_url": null, "type": "USER", "referred_at": "2026-09-18T14:15:22.000Z" } ] } ``` #### ``2. `200 OK` — No Referrals Yet`` ``` json { "referral_code": "CAP_8X9K2", "total_referred": 0, "referred_users": [] } ``` #### ``3. `401 Unauthorized` — Missing / Expired Token / Revoked Session`` ``` json { "error": "Unauthorized", "message": "Invalid or expired driver access token." } ``` #### ``4. `403 Forbidden` — Account Blocked / Deactivated`` ``` json { "error": "Forbidden", "message": "Driver account is blocked or deactivated." } ``` #### ``5. `404 Not Found` — Referral Code Not Found`` ``` json { "error": "Referral code not found for driver" } ``` #### `` 6. `500 Internal Server Error` `` ``` json { "error": "Failed to fetch referral data" } ``` --- ### `Status Codes Reference` | HTTP Status Code | Condition | | --- | --- | | **`200 OK`** | Successfully retrieved driver referral code and referee network. | | **`401 Unauthorized`** | Missing, invalid, expired token or session revoked. | | **`403 Forbidden`** | Driver account has been deactivated or blocked. | | **`404 Not Found`** | Driver has no referral code assigned. | | **`500 Internal Server Error`** | Database or query execution failure. |