Validate Referral Code
# Validate Referral Code
A public endpoint to check whether a referral code is valid prior to registration or sign-in. Searches across both users and drivers databases, and returns the referrer type (`USER` or `DRIVER`) with a privacy-masked referrer name.
---
### Endpoint Overview
- **Method:** `POST`
- **Route:** `/api/v1/referral/validate`
- **Authentication:** `None (Public)`
- **Content-Type:** `application/json`
---
### Request Headers
| Header | Type | Required | Description |
| --- | --- | --- | --- |
| `Content-Type` | `string` | **Yes** | Must be `application/json` |
---
### Request Body Schema
| Field | Data Type | Required | Default | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- | --- |
| `referral_code` | `string` | **Yes** | — | Min length 1 (e.g. `"CAP_8X9K2"`, `"USR_1A2B3"`) | Referral code to validate |
#### Example Request Body
``` json
{
"referral_code": "CAP_8X9K2"
}
```
---
### Response Body Schema (`200 OK`)
| Field | Data Type | Optional | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- |
| `valid` | `boolean` | No | `true`, `false` | Whether the referral code is active and exists |
| `referrer_type` | `enum` | Yes | `"USER"`, `"DRIVER"` | Platform role of code owner (omitted if invalid) |
| `referrer_name` | `string` | Yes | Masked string or `null` | Masked name for privacy (e.g. `"Ravi K**\*"`) |
---
### Response Examples
#### 1\. `200 OK` — Valid Driver Referral Code
``` json
{
"valid": true,
"referrer_type": "DRIVER",
"referrer_name": "Ravi K***"
}
```
#### 2\. `200 OK` — Valid User Referral Code
``` json
{
"valid": true,
"referrer_type": "USER",
"referrer_name": "Ananya S***"
}
```
#### 3\. `200 OK` — Invalid / Non-Existent Referral Code
``` json
{
"valid": false
}
```
#### 4\. `400 Bad Request` — Validation Error (Missing `referral_code`)
``` json
{
"success": false,
"message": "Validation failed: referral_code: Referral code is required",
"errors": [
{
"field": "referral_code",
"message": "Referral code is required"
}
]
}
```
#### 5\. `500 Internal Server Error`
``` json
{
"error": "Failed to validate referral code"
}
```
---
### Status Codes Reference
| HTTP Status Code | Condition |
| --- | --- |
| **`200 OK`** | Code validated successfully (returns `valid: true` or `valid: false`). |
| **`400 Bad Request`** | Missing or empty `referral_code` in request body. |
| **`500 Internal Server Error`** | Server or database lookup error. |
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.